The  Definitive  Guides 
to  the  X Window  System 


Volume  Three 


O'Reilly  & Associates,  Inc. 


X Window  System 
User’s  Guide 


Books  That  Help  People  Get  More  Out  of  Computers 


X Protocol  Reference  Manual,  r-4  Release,  soo  pages 

Describes  the  X Network  Protocol  which  underlies  all  software  for  Version  11  of  the  X Window  System. 

XI ib  Programming  Manual,  r-4  Release,  672  pages 
Xlib  Reference  Manual,  r-4  Release,  792  pages 

Complete  programming  and  reference  guides  to  the  X library  (Xlib),  the  lowest  level  of  programming 
interface  to  X. 

X Window  System  User’s  Guide,  r-4  Release 

Orients  the  new  user  to  window  system  concepts,  provides  detailed  tutorials  for  many  client  programs,  and 
explains  how  to  customize  the  X environment. 

Standard  Edition,  752  pages 
Motif  Edition,  734  pages 

X Toolkit  Intrinsics  Programming  Manual,  r-4  Release 

Complete  guide  to  programming  with  Xt  Intrinsics,  the  library  of  C language  routines  that  facilitate  the  design 
of  user  interfaces,  with  reusable  components  called  widgets. 

Standard  Edition,  624  pages 
Motif  Edition,  666  pages 

X Toolkit  Intrinsics  Reference  Manual,  r-4  Release,  776  pages 

Complete  programmer’s  reference  for  the  X Toolkit. 

Motif  Programming  Manual,  Motif  1.1, 1032  pages 

Complete  guide  to  programming  for  the  Motif  graphical  user  interface. 

XView  Programming  Manual,  xview  version  3.0, 768 pages 
XView  Reference  Manual,  266  pages 

Complete  information  on  programming  with  XView,  an  easy-to-use  toolkit  that  is  widely  available. 

The  X Window  System  in  a Nutshell,  R-3  and  R-4  Release,  380  pages 

A single-volume  quick  reference  that  is  an  indispensable  companion  to  the  series. 


Contact  us  for  a catalog  of  our  books,  for  orders,  or  for  more  Information. 

O’Reilly  & Associates,  Inc. 


632  Petaluma  Avenue,  Sebastopol  CA  95472 
(800)  338-6887  US/Canada  707-829-05 1 5 overseas/local  707-829-0104  Fax 


Volume  Three 


X Window  System 
User’s  Guide 


for  XI 1 R3  and  R4  of  the 
X Window  System 


by  Valerie  Quercia  and  Tim  O’Reilly 


O’Reilly  & Associates,  Inc. 


Copyright  © 1990  O’Reilly  & Associates,  Inc. 

All  Rights  Reserved 

Ardent  is  a trademark  of  Star  dent  Computer  Inc. 

Charter  is  a registered  trademark  of  Bitstream,  Inc. 

DEC  is  a registered  trademark  of  Digital  Equipment  Corporation. 

Gumby  is  a copyright  of  Prema  Toy  Company,  Inc. 

Lucida  is  a registered  trademark  of  Bigelow  & Holmes. 

Macintosh  is  a registered  trademark  of  Apple  Computer,  Inc. 

MacWrite  is  a registered  trademark  of  CLARIS  Corporation. 

Motif,  OSF,  and  OSF /Motif  are  trademarks  of  the  Open  Software  Foundation,  Inc. 
NEWS  is  a trademark  of  the  Sony  Corporation. 

NCD16  is  a trademark  of  Network  Computing  Devices,  Inc. 

OPEN  LOOK  is  a trademark  of  AT&T. 

PostScript  is  a registered  trademark  of  Adobe  Systems  Inc. 

Sun-3,  S unView,  and  Xll/NeWS  are  trademarks  of  Sun  Microsystems,  Inc. 
Tektronix  is  a registered  trademark  of  Tektronix  Inc. 

Tetris  is  a trademark  of  AcademySoft-ELORG. 

Times,  Helvetica,  and  New  Century  Schoolbook  are  registered  trademarks  of  Linotype. 
UNIX  is  a registered  trademark  of  AT &T. 

X Display  Station  is  a trademark  of  Visual  Technology  Incorporated. 

The  X Window  System  is  a trademark  of  the  Massachusetts  Institute  of  Technology. 
The  systemmwmrc  file  in  Appendix  C is  reprinted  with  permission  from 
Open  Software  Foundation. 


Printing  and  Revision  History 


Sept.  1988: 
July  1989: 
Oct.  1989: 
May  1990: 


First  Edition 

Second  Edition.  Revised  to  reflect  Release  3. 
Minor  corrections. 

Third  Edition.  Revised  to  reflect  Release  4. 


Small  Print 


Portions  of  this  manual,  especially  the  reference  pages  in  Part  Three,  are  based  on  reference  materials  provided  on 
the  XI 1 R4  tape,  which  are  copyright  © 1985,  1986,  1987,  1988,  1989,  1990  the  Massachusetts  Institute  of  Technol- 
ogy, Cambridge,  Massachusetts,  and  Digital  Equipment  Corporation,  Maynard,  Massachusetts. 

We’ve  used  this  material  under  the  terms  of  its  copyright,  which  grants  free  use,  subject  to  the  following  conditions: 
“Permission  to  use,  copy,  modify  and  distribute  this  documentation  (i.e„  the  original  MIT 
and  Digital  material)  for  any  purpose  and  without  fee  is  hereby  granted,  provided  that  the 
above  copyright  notice  appears  in  all  copies  and  that  both  that  copyright  notice  and  this  per- 
mission notice  appear  in  supporting  documentation,  and  that  the  name  of  MTT  or  Digital  not 
be  used  in  advertising  or  publicity  pertaining  to  distribution  of  the  software  without  specific, 
written  prior  permission.  MTT  and  Digital  make  no  representations  about  the  suitability  of 
the  software  described  herein  for  any  purpose.  It  is  provided  ‘as  is’  without  expressed  or 
implied  warranty.” 

Note,  however,  that  those  portions  of  this  document  that  are  based  on  the  original  XI 1 documentation  and  other 
source  material  have  been  significantly  revised,  and  that  all  such  revisions  are  copyright  © 1987,  1988,  1989,  1990 
O’Reilly  & Associates,  Inc.  Inasmuch  as  the  proprietary  revisions  can’t  be  separated  from  the  freely  copyable  MIT 
source  material,  the  net  result  is  that  copying  of  this  document  is  not  allowed.  Sorry  for  the  doublespeak! 

While  every  precaution  has  been  taken  in  the  preparation  of  this  book,  we  assume  no  responsibility  for  errors  or 
omissions.  Neither  is  any  liability  assumed  for  damages  resulting  from  the  use  of  the  information  contained  herein. 


[10/91] 


ISBN  0-937175-14-5 


Table  of  Contents 


Page 

Preface xxi 

Assumptions xxi 

Organization  xxii 

Bulk  Sales  Information  xxiv 

xshowfonts.c  xxiv 

Acknowlegements  xxiv 

Font  and  Character  Conventions  xxv 

PART  ONE:  Using  X l 

1 An  Introduction  to  the  X Window  System 5 

Anatomy  of  an  X Display 5 

X Architecture  Overview  10 

The  X Display  Server  1 1 

Clients 12 

The  Window  Manager 13 

The  xterm  Terminal  Emulator 14 

The  Display  Manager  14 

Other  X Clients  14 

Customizing  Clients  15 

2 Getting  Started  19 

If  X is  Being  Started  Automatically  19 

Starting  X Manually  22 

Starting  the  First  xterm  Window  22 

Bringing  Up  the  Window  Manager  23 

Starting  a Second  xterm  Window 23 

Exiting  from  an  xterm  Window  25 

Special  Keys 26 

How  a Client  Looks  and  Behaves:  Application  Defaults  26 

Starting  Other  Clients 27 

Running  a Client  on  Another  Machine  28 

Where  to  Go  From  Here 30 


3 Using  the  twm  Window  Manager  33 

Starting  the  Window  Manager 34 

Titlebars 34 

The  Twm  Menu  35 

Displaying  Windows  as  Icons 36 

Resizing  Windows 38 

Moving  Windows  and  Icons  39 

Shuffling  the  Window  Stack:  Raise  and  Lower 40 

Raising  Windows  (bringing  in  front  of  others) 41 

Lowering  Windows  (sending  behind  others) 42 

Changing  Keyboard  Focus 43 

Removing  a Window:  Delete  and  Kill  43 

Restarting  the  Window  Manager 44 

Exiting  the  Window  Manager 44 

Button  Control  of  Window  Manager  Functions 45 

Using  twm  to  Place  Other  Clients  45 

Customizing  twm 46 

Some  of  My  Keystrokes  are  Missing  46 

4 The  \term  Terminal  Emulator  49 

The  Release  4 xterm  Menus 50 

The  xterm  Menus  at  a Glance  50 

The  Main  Options  Menu  52 

VT  Options  Menu  55 

VT  Fonts  Menu  57 

Tek  Options  Menu 58 

Using  the  Scrollbar  59 

Copying  and  Pasting  Text  Selections  61 

Selecting  Text  to  Copy  62 

Pasting  Text  Selections 64 

Manipulating  Text  Selections  65 

Copying  and  Pasting  between  Release  2 and  3 Clients:  xcutsel  66 

Saving  Multiple  Selections:  xclipboard  (Release  4 Version) 68 

Problems  with  Large  Selections  71 

Editing  Text  Saved  in  the  xclipboard  71 

Release  3 xclipboard  72 

Terminal  Emulation  and  the  xterm  Terminal  Type 73 

Resizing  an  xterm  Window 74 

Running  a Program  in  a Temporary  xterm  Window  75 

5 Font  Specification  79 

Font  Naming  Conventions  80 

Font  Families 81 

vi 


Stroke  Weight  and  Slant 84 

Font  Sizes  84 

Other  Information  in  the  Font  Name 87 

Font  Name  Wildcarding  88 

The  Font  Search  Path 90 

The  fonts.dir  Files 91 

Font  Name  Aliasing 93 

Making  the  Server  Aware  of  Aliases  95 

Utilities  for  Displaying  Information  about  Fonts 95 

The  Font  Displayer:  xfd  95 

Release  3 xfd 97 

Previewing  and  Selecting  Fonts:  xfontsel 98 

Previewing  Fonts  with  the  xfontsel  Menus 98 

Selecting  a Font  Name  102 

Changing  Fonts  in  xterm  Windows 102 

The  Great  Escape 102 

The  Selection  Menu  Item 104 

Release  2 versus  Subsequent  Release  Fonts 104 

Font  Specification  in  Release  2 104 

6 Graphics  Utilities  109 

Creating  Icons  and  Other  Bitmaps  109 

Bitmap  Editing  Commands 1 1 1 

Pointer  Commands 1 12 

Bitmap  Command  Boxes  112 

Acting  on  the  Entire  Grid:  Clear  All,  Set  All,  Invert  All 1 12 

Acting  on  an  Area:  Clear  Area,  Set  Area,  Invert  Area  1 14 

Copy  Area,  Move  Area,  Overlay  Area 115 

Drawing:  Line,  Circle,  Filled  Circle  116 

Filling  in  a Shape:  Rood  Fill  117 

Hot  Spots:  Set  Hot  Spot,  Clear  Hot  Spot  1 17 

Saving  and  Quitting:  Write  Output,  Quit 1 17 

Creating  a Bitmap  from  a Cursor  119 

Magnifying  Portions  of  the  Screen:  xmag  122 

Quitting  xmag  123 

What  xmag  Shows  You  123 

Dynamically  Choosing  a Different  Source  Area 125 

7 Other  Clients  129 

Desk  Accessories  129 

Clock  Programs:  xclock  and  oclock 130 

A Scientific  Calculator:  xcalc 132 

Terminating  the  calculator  133 

Mail  Notification  Client:  xbiff 133 

vii 


Monitoring  System  Load  Average:  xload 134 

Browsing  Reference  Pages:  xman 135 

Release  3 xman 138 

Printing  Utilities:  xwd,  xpr,  xdpr 140 

Killing  a Client  Window  with  xkill 141 

Problems  with  Killing  a Client  142 

Window  and  Display  Information  Clients 144 

Displaying  Information  about  a Window:  xwininfo 144 

Listing  the  Window  Tree:  xlswins 146 

Listing  the  Currently  Running  Clients:  xlsclients 148 

Generating  Information  about  the  Display:  xdpyinfo 149 

User-contributed  Clients  150 

X Toolkit  Applications  150 

Dialog  Boxes  and  Command  Buttons  151 

Scrollbars 152 

Selecting  Information  for  Copying  and  Pasting 152 

Vertical  Panes 153 

Viewports  154 

Text  Editing  Widget 154 

PART  TWO:  Customizing  X 159 

8 Command  Line  Options  163 

Which  Display  to  Run  On 164 

Title  and  Name 165 

Window  Geometry 166 

Border  Width 168 

Color  Specification  169 

The  rgb.txt  File 169 

Release  4 Color  Names  170 

Release  3 Color  Names  172 

Alternative  Release  4 Color  Databases 172 

Hexadecimal  Color  Specification 172 

The  RGB  Color  Model  173 

How  Many  Colors  are  Available?  174 

Starting  a Client  Window  as  an  Icon 176 

Specifying  Fonts  on  the  Command  Line 176 

Reverse  Video 177 

9 Setting  Resources  181 

Resource  Naming  Syntax 182 

Syntax  of  Toolkit  Client  Resources 183 

Tight  Bindings  and  Loose  Bindings 184 

Instances  and  Classes  184 

viii 


Precedence  Rules  for  Resource  Specification  185 

Some  Common  Resources  187 

Event  Translations  188 

The  Syntax  of  Event  Translations 189 

xterm  Translations  to  Use  xclipboard 191 

How  to  Set  Resources 192 

A Sample  Resources  File  193 

Specifying  Resources  from  the  Command  Line 194 

The  -xrm  Option 194 

The -name  Option  194 

Setting  Resources  with  xrdb 195 

Querying  the  Resource  Database  196 

Loading  New  Values  into  the  Resource  Database  196 

Saving  Active  Resource  Definitions  in  a File 197 

Removing  Resource  Definitions 197 

Listing  the  Current  Resources  for  a Client:  appres 198 

Other  Sources  of  Resource  Definition 199 

10  Customizing  the  twm  Window  Manager  203 

Setting  .twmrc  Variables  205 

Button/Key  Bindings 206 

Pointer  Buttons  206 

Keys  207 

Context  207 

Function  Names  208 

Action  208 

Defining  Menus 209 

Submenus  210 

Executing  System  Commands  from  a Menu 21 1 

Color  Menus 212 

A Complete  Revamp  of  twm  213 

11  Setup  Clients  219 

xset:  Setting  Display  and  Keyboard  Preferences  219 

Keyboard  Bell  219 

Bug  Compatibility  Mode  220 

Keyclick  Volume 220 

Enabling  or  Disabling  Auto-repeat  221 

Changing  or  Rehashing  the  Font  Path 221 

Keyboard  LEDs 221 

Pointer  Acceleration  222 

Screen  Saver 222 

Color  Definition  223 

Help  with  xset  Options 223 


IX 


xsetroot:  Setting  Root  Window  Characteristics  224 

Setting  Root  Window  Patterns 224 

Foreground,  Background  Color  and  Reverse  Video 225 

Changing  the  Root  Window  Pointer  226 

xmodmap:  Modifier  Key  and  Pointer  Customization  227 

Keycodes  and  Keysyms 229 

Procedure  to  Map  Modifier  Keys  230 

Displaying  the  Current  Modifier  Key  Map 230 

Determining  the  Default  Key  Mappings 231 

Matching  Keysyms  with  Physical  Keys  Using  xev 232 

Changing  the  Map  with  xmodmap 233 

Expressions  to  Change  the  Key  Map  234 

Key  Mapping  Examples 235 

Displaying  and  Changing  the  Pointer  Map 236 

PART  THREE:  Client  Reference  Pages  239 

PART  FOUR:  Appendices  521 

A System  Management  525 

Including  X in  Your  Search  Path 526 

Setting  the  Terminal  Type  526 

A Startup  Shell  Script 527 

What  Should  Go  in  the  Script 527 

Starting  X 531 

Starting  X with  the  Display  Manager,  xdm  (Release  4)  531 

Getting  Started  with  xdm  on  a Single  Display  532 

Setting  Up  the  Configuration  File  and  Other  Special  Files 532 

The  Standard  Login  Session  535 

Customizing  xdm 536 

The  Xservers  File 537 

The  Xsession  File  and  .xsession  Scripts 538 

The  Xresources  File 538 

The  Error  Log  File  539 

The  xdm-pid  File  (Release  4 Only) 539 

Xstartup  and  Xreset 539 

Security  and  the  authorize  Resource  (Release  4 Only)  539 

Stopping  xdm  and  the  Server 540 

X Terminals  and  the  XDM  Control  Protocol  (Release  4) 540 

Release  3 xdm 541 

Release  3 Special  Files  and  the  Config  File  541 

Customizing  the  Release  3 xdm  542 

Managing  Multiple  Displays:  the  Release  3 Xservers  File  543 

Release  3 .xsession  Scripts 544 


x 


Release  3 Xresources  File 544 

Release  3 Xstartup  and  Xreset 544 

Starling  X with  xinit 545 

An  Older  Method  of  Starting  X:  /etc/ttys  545 

Server  Access  Control 547 

Host-based  Access  and  the  xhost  Client  547 

User-based  Access:  xdm  and  the  .Xauthority  File  (Release  4) 548 

Font  Management 549 

Console  Messages 550 

Log  Files 550 

Changing  the  Color  Name  Database 550 

B The  uwm  Window  Manager  555 

Starting  the  Window  Manager 556 

The  WindowOps  Menu  556 

Creating  New  Terminal  Windows  558 

C The  OSF/Motif  Window  Manager  591 

Getting  Started  with  mwm 591 

Starting  mwm 592 

Selecting  the  Window  to  Receive  Input  592 

Manipulating  Windows  with  the  mwm  Window  Frame 594 

Moving  a Window:  The  Title  Area  594 

Minimizing  (Iconifying)  and  Maximizing  a Window  596 

The  Minimize  Button  596 

The  Maximize  Button 597 

Raising  a Window 598 

Resizing  a Window 599 

The  Window  Menu  Button:  Display  a Menu  or  Close  the  Window 602 

Manipulating  Windows  Using  the  Window  Menu 602 

Changing  the  Window  Location:  Move 604 

Resizing  the  Window:  Size 605 

Iconifying  the  Window:  Minimize 605 

Changing  to  the  Maximum  Size:  Maximize 606 

Moving  a Window  to  the  Bottom  of  the  Stack:  Lower 606 

Removing  a Window:  Close  606 

Restoring  a Maximized  Window  or  an  Icon:  Restore 607 

Manipulating  Icons 607 

Manipulating  Icons  Using  the  Window  Menu  607 

The  Root  Menu  608 

Customizing  mwm 610 

Activating  Changes  to  the  Window  Manager  61 1 

The  system.mwmrc  File  612 

mwm  Functions 614 


XI 


Menu  Specifications  615 

Key  Bindings 616 

Button  Bindings  617 

Customizing  the  Root  Menu 619 

Creating  New  Menus 620 

Cascading  Menus 620 

Setting  mwm  Resources  622 

Component  Appearance  Resources 623 

mwm-Specific  Appearance  and  Behavior  Resources  624 

Client-Specific  Resources  624 

Setting  the  Focus  Policy 625 

Using  an  Icon  Box  626 

D Standard  Cursors  633 

E Release  3 and  4 Standard  Fonts  639 

F xterm  Control  Sequences  681 

xterm  Control  Sequences  681 

Definitions  681 

VT 102  Mode 681 

Tektronix  4014  Mode  688 

G Standard  Bitmaps  693 

H Translation  Table  Syntax  697 

Event  Types  and  Modifiers 697 

Detail  Field 699 

Modifiers  700 

Complex  Translation  Examples 700 

Glossary  705 

Index 711 


xii 


Figures 


Page 

1-1  X display  with  five  windows  and  an  icon 6 

1-2  Some  standard  cursors  8 

1-3  Focus  on  an  xterm  window 9 

1-4  Twm  menu  on  the  root  window 10 

1-5  A display  made  up  of  two  physical  screens  1 1 

1- 6  A sample  X Window  System  configuration  12 

2- 1  Workstation  with  login  xterm  window  on  the  root  window 20 

2-2  xdm  login  window 21 

2-3  xterm  window  with  login  prompt 21 

2-4  Placing  a second  xterm  window 24 

2-5  Two  xterm  windows 24 

2-6  The  oclock  display  28 

2- 7  Monitoring  activity  on  two  systems  with  xload 29 

3- 1  Anatomy  of  a twm  titlebar 35 

3-2  Twm  menu  36 

3-3  The  login  window  is  about  to  become  an  icon 37 

3-4  The  login  window  is  about  to  be  deiconified  37 

3-5  Resizing  a window  39 

3-6  Moving  windows  or  icons  40 

3-7  One  xterm  window  overlapping  another 41 

3- 8  Raising  a window 42 

4- 1  The  Release  4 xterm  menus 5 1 

4-2  The  Main  Options  menu  52 

4-3  Reverse  video  is  enabled  when  the  keyboard  is  secure 54 

4-4  The  VT  Options  menu 56 

4-5  VT  Fonts  menu  57 

4-6  The  Tek  Options  menu 59 

4-7  An  xterm  window  with  a scrollbar 60 

4-8  Highlighted  text  saved  as  the  PRIMARY  selection  63 

4-9  Pasting  text  into  an  open  file  64 

4-10  An  xcutsel  window 67 

4-11  The  xclipboard  window  68 

4-12  Selected  text  appears  automatically  in  the  xclipboard  window  69 

4-13  xclipboard  with  scrollbars  to  view  large  text  selection 71 

4- 14  The  Release  3 xclipboard  window 72 

5- 1  Font  name,  Releases  3 and  4 81 

5-2  The  major  commercial  font  families  available  in  the  standard  X distribution  82 

5-3  Miscellaneous  fonts  for  xterm  text  83 

5-4  The  same  fonts  in  different  weights  and  slants 85 

5-5  The  same  font  in  six  different  point  sizes 85 

5-6  The  100-dpi  version  of  a 24-point  font  appears  larger  on  a 75-dpi  monitor 86 

5-7  Fixed  font,  6x13  pixels  96 

5-8  xfontsel  window  displaying  7x13  bold  font 99 

xi '// 


5-9  xfontsel  window  with  foundry  menu  displayed 

5-10  xfontsel  after  choosing  Adobe  from  the  foundry  menu 

5- 11  Default  font,  fixed  

6- 1  Bitmap  window  

6-2  Gumby  bitmap 

6-3  Clearing  all  

6-4  Setting  all 

6-5  Inverting  all  

6-6  Selecting  an  area  to  clear,  set,  or  invert 

6-7  Selecting  an  area  to  copy,  move,  or  overlay  

6-8  Selecting  center  and  radius  of  circle 

6-9  Bitmap  window  with  quit  dialog  box  

6-10  ASCII  array  representing  the  pound  sign 

6-11  /tmp/gumby .array  

6-12  Bitmap  of  the  Gumby  cursor 

6-13  gumby.array  padded  by  hyphens 

6-14  xmag  window  displaying  magnified  screen  area 

6- 15  Displaying  pixel  statistics  with  xmag 

7- 1  Two  xclock  displays:  analog  clock  above  digital  clock  . 

7-2  oclock  display 

7-3  Oblong  oclock  display 

7-4  The  default  xcalc  (TI-30  mode)  on  the  screen  

7-5  xbiff  before  and  after  mail  is  received 

7-6  A sample  xload  window  

7-7  Initial  xman  window  

7-8  Xman  Options  menu  

7-9  cd  reference  page  displayed  in  xman  window 

7-10  Xman  Sections  menu  

7-11  Release  3 Xman  Options  menu 

7-12  Selecting  the  window  to  be  removed 

7-13  Window  information  displayed  by  xwininfo  

7-14  Window  tree  displayed  by  xlswins 

7-15  Window  tree  with  geometry  specifications 

7-16  Long  xlsclients  listing 

7-17  A dialog  box  with  Yes,  No,  and  Cancel  command  buttons  ..... 

7-18  An  xterm  window  with  scrollbar  

7-19  Vertical  panes  and  grips  in  the  xmh  client  

7- 20  xman  uses  a viewport  widget 

8- 1  Window  offsets 

8- 2  Multiple  planes  used  to  index  a colormap 

9- 1  Selected  text  appears  automatically  in  the  xclipboard  window 

9-2  A sample  resources  file 

11-1  Partial  keymap  table  

11-2  xev  window  

11-3  Pointer  map 

A-l  Display  after  running  sample  script 

A-2  Default  xdm-config  file,  Release  4 

A-3  Default  xdm-config  file,  Release  3 


....  100 
....  100 
....  106 
....  110 
....  Ill 
....  112 
....  113 
....  113 
....  114 
....  115 
....  116 
....  118 
....119 
....  120 
....  121 
....  121 
....  123 
....  124 
....  130 
....  131 
....  131 
....  132 
....  134 
....  134 
....  135 
....  136 
....  137 
....  138 
....  139 
....  142 
....  145 
....  147 
....  147 
....  149 
....  151 
....  153 
....  154 
....  155 
....  167 
....  175 
....  192 
....  193 
....  232 
....  233 
....  237 
....  530 
....  533 
....  542 


XIV 


A-4  Typical  Xservers  file  for  a workstation,  Release  3 542 

B-l  WindowOps  menu 557 

B-2  A default-size  xtcrm  window  558 

B-3  A custom-size  xterm  window 559 

B-4  A maximum-height  xterm  window  560 

B-5  Moving  windows  or  icons 561 

B-6  Resizing  a window  562 

B-7  One  xterm  window  overlapping  another  563 

B-8  Raising  a window  564 

B-9  The  login  window  is  about  to  become  an  icon 566 

B-10  The  login  window  is  about  to  be  deiconified  567 

B-ll  Preferences  menu  571 

C-l  mwm  is  running  on  the  display 593 

C-2  An  xterm  window  running  with  the  OSF/Motif  window  manager 594 

C-3  Moving  a window  by  dragging  the  title  area 595 

C-4  Converting  a window  to  an  icon  with  the  Minimize  button 596 

C-5  xterm  window  icon  under  mwm 597 

C-6  Maximizing  a window  598 

C-7  The  outer  frame  is  divided  into  four  long  borders  and  four  comers 599 

C-8  Window  with  resizing  pointer  600 

C-9  Resizing  pointer  symbols 600 

C-10  Dragging  the  comer  to  make  a window  larger 601 

C-l  1 The  Window  Menu 603 

C-12  The  mwm  Root  Menu  609 

C-13  An  arrow  pointing  to  the  right  indicates  a submenu 621 

C-14  Utilities  submenu  of  the  Root  Menu 622 

C-l 5 An  icon  box 626 

C-16  In  the  resized  icon  box,  only  three  icons  are  visible 628 

C-l 7 Packlcons  menu  item  rearranges  icons  in  resized  box  628 

D-l  The  Standard  Cursors 635 

G-l  The  Standard  Bitmaps 694 


xv 


Examples 


Page 

5-1  Subsection  of  the  Release  4 fonts. dir  file  in  /usr/lib/Xl  1/fonts/l 00dpi  92 

5-2  Sample  fonts.alias  file  entries 93 

9- 1  Sample  resources 187 

10- 1  The  system  .twmrc  file  from  the  MIT  distribution  203 

10-2  The  Utilities  menu 209 

10-3  The  Preferences  menu 210 

10-4  Window  operations  divided  into  three  menus  210 

10-5  A Useful  Commands  menu 211 

10-6  A menu  with  color  definitions 212 

10-7  Modified  .twmrc  file 214 

A-l  Startup  Bourne  shell  script  528 

C-l  The  system.mwmrc  file,  Release  1.0 612 

E-l  xshowfont  source  listing  674 


XVI 


Tables 


Page 

3- 1.  Keyboard  Shortcuts  for  Window  Manager  Functions  45 

4- 1.  VT  Fonts  Menu  Defaults  58 

4-2.  Button  Combinations  to  Select  Text  for  Copying  62 

4- 3.  Command  Buttons  and  Functions  69 

5- 1.  Fixed  Font  Aliases  and  Font  Names  83 

5-2.  Essential  Elements  of  a Font  Name  90 

5-3.  Standard  Font  Directories,  Releases  3 and  4 91 

5-4.  Fonts  in  the  Standard  Distribution,  Release  2 105 

8-1.  Standard  Options  163 

8- 2.  Geometry  specification  x and  y offsets  166 

9- 1.  Core  Toolkit  Resources  187 

A- 1.  xdm  Special  Files  533 

C-l.  Window  Menu  Actions  on  an  Icon  608 

C-2.  Resource  Names  Corresponding  to  mwm  Components  623 

D-l.  Standard  Cursor  Symbols  634 

E-l.  Fonts  in  the  misc  Directory,  Release  4 640 

E-2.  Fonts  in  the  75dpi  Directory,  Release  4 641 

E-3.  Fonts  in  the  100dpi  Directory,  Release  4 646 

E-4.  Fonts  in  the  misc  Directory,  Release  3 651 

E-5.  Fonts  in  the  75dpi  Directory,  Release  3 651 

E-6.  Fonts  in  the  100dpi  Directory,  Release  3 654 

G-l.  Standard  Bitmaps  Available  as  of  Release  4 693 

H-l.  Event  Types  and  Their  Abbreviations  697 

H-2.  Key  Modifiers  699 

H-3.  Event  Modifiers  and  their  Meanings  700 


xvii 


Preface 


By  convention,  a preface  introduces  the  book  itself,  while  the  introduction 
starts  in  on  the  subject  matter.  You  should  read  through  the  preface  to  get 
an  idea  of  how  the  book  is  organized,  the  conventions  it  follows,  and  so  on. 

In  The  Preface: 

Assumptions  xxi 

Organization xxii 

Bulk  Sales  Information xxiv 

xshowfonts.c  xxiv 

Acknowledgements  xxiv 

Font  and  Character  Conventions xxv 


Preface 


The  X Window  System™  is  a network-based  graphics  windowing  system  for  workstations.  It 
was  developed  by  MIT,  and  has  been  adopted  as  an  industry  standard.  The  X Window  System 
User' s Guide  describes  window  system  concepts  and  the  application  programs  (clients)  com- 
monly distributed  with  Version  11,  Release  4 of  X.  Because  some  commercial  X systems 
still  reflect  XI 1,  Release  3,  we  highlight  important  differences  between  the  two. 

Assumptions 

This  book  assumes  that  X has  already  been  installed  on  your  system,  and  that  all  standard 
MIT  clients  are  available.  In  addition,  although  X runs  on  many  different  types  of  systems, 
this  book  assumes  that  you  are  running  it  on  a UNIX®  system,  and  that  you  have  basic  famil- 
iarity with  UNIX.  If  you  are  not  using  UNIX,  you  will  still  find  the  book  useful — UNIX 
dependencies  are  not  that  widespread — but  you  may  occasionally  need  to  translate  a com- 
mand example  into  its  equivalent  on  your  system.  The  book  also  assumes  that  you  are  using 
a 3-button  pointer,  and  that  the  operation  of  the  twm  window  manager  is  controlled  by  the 
system.twmrc  file  from  the  MIT  XI 1 distribution  (if  this  is  not  the  case,  the  book  provides 
information  that  will  allow  you  to  understand  how  twm  is  configured  on  your  system). 

This  book  has  been  written  for  both  first  time  and  experienced  users  of  the  X Window  Sys- 
tem. First-time  users  should  read  the  book  in  order,  starting  with  Chapter  1. 

Experienced  users  can  use  this  book  as  a reference  for  the  client  programs  detailed  here. 
Since  there  is  great  flexibility  with  X,  even  frequent  users  need  to  check  on  the  syntax  and 
availability  of  options.  Reference  pages  for  each  client  detail  command-line  options,  cus- 
tomization database  (resource  database)  variables,  and  other  detailed  information. 
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Organization 

The  book  contains  the  following  parts: 

Part  One:  Using  X 


Preface 

Describes  the  book’s  assumptions,  audience,  organization,  and  conventions. 

Chapter  1:  An  Introduction  to  the  X Window  System 

Describes  the  basic  terminology  associated  with  the  X Window  System:  server, 
client,  window,  etc.  The  most  important  X clients  are  described. 

Chapter  2:  Getting  Started 

Shows  the  basics  of  using  X:  starting  the  server  and  creating  the  first  terminal 
window;  starting  the  window  manager;  adding  additional  windows;  exiting. 
This  chapter  is  tutorial  in  nature:  you  can  follow  along  at  a workstation  as  you 
read. 

Chapter  3:  Using  the  twm  Window  Manager 

Describes  how  to  use  the  twm  window  manager.  This  client  is  used  to  manipu- 
late windows  on  the  screen. 

Chapter  4:  The  xterm  Terminal  Emulator 

Describes  how  to  use  the  xterm  terminal  emulator,  the  most  frequently-used  cli- 
ent. Certain  aspects  of  x term  operation  described  in  this  chapter,  such  as  scrol- 
ling and  “copy  and  paste,”  are  common  to  other  applications  as  well. 

Chapter  5:  Font  Specification 

Describes  the  somewhat  complicated  font  naming  conventions  and  ways  to  sim- 
plify font  specification,  including  wildcarding  and  aliasing.  Describes  how  to 
use  the  xlsfonts,  xfd,  and  xfontsel  clients  to  list,  display,  and  select  available  dis- 
play fonts.  Since  the  available  fonts  and  font  naming  conventions  changed  radi- 
cally from  Release  2 to  Release  3,  this  chapter  also  reviews  these  changes. 

Chapter  6:  Graphics  Utilities 

Explains  how  to  use  the  major  graphics  clients  included  with  X,  notably  the  bit- 
map editor. 

Chapter  7:  Other  Clients 

Gives  an  overview  of  other  clients  available  with  X,  including  window  and  dis- 
play information  clients,  the  xkill  program,  and  several  “desk  accessories.” 

Part  Two:  Customizing  X 

Chapter  8:  Command  Line  Options 

Discusses  some  of  the  command  line  options  that  are  common  to  most  clients. 
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Chapter  9:  Setting  Resources 

Tells  how  to  use  create  an  J (resources  file,  or  other  file,  to  set  resources  for  client 
applications.  This  chapter  also  describes  how  to  use  xrdb,  which  saves  you  hav- 
ing to  maintain  multiple  ^resources  files  if  you  run  clients  on  multiple 
machines. 

Chapter  10:  Customizing  the  twin  Window  Manager 

Describes  the  .twmrc  file  by  showing  the  default  file  shipped  by  MIT,  and  then 
examining  the  purpose  and  syntax  of  entries.  Explains  various  techniques  for 
revising  the  .twmrc  file  to  modify  existing  menus  and  create  new  ones.  A 
revised  .twmrc  file  is  also  offered  for  users  to  copy. 

Chapter  11:  Setup  Clients 

Describes  how  to  set  display  and  keyboard  preferences  using  xset  and  how  to  set 
root  window  preferences  using  xsetroot.  Demonstrates  how  to  redefine  the  logi- 
cal keynames  and  pointer  commands  recognized  by  X using  xmodmap. 

Part  Three:  Client  Reference  Pages 

Extended  reference  pages  for  all  clients. 

Part  Four:  Appendices 

Appendix  A:  System  Management 
Appendix  B:  The  uwm  Window  Manager 
Appendix  C:  The  OSF/Motif  Window  Manager 
Appendix  D:  Standard  Cursors 
Appendix  E:  Release  3 and  4 Standard  Fonts 
Appendix  F:  xterm  Control  Sequences 
Appendix  G:  Standard  Bitmaps 
Appendix  H:  Translation  Table  Syntax 
Glossary 


Index 
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Bulk  Sales  Information 


This  guide  is  being  resold  by  many  workstation  manufacturers  as  their  official  X Window 
System  documentation.  For  information  on  volume  discounts  for  bulk  purchases,  call 
O’Reilly  & Associates,  Inc.,  at  800-338-6887  (in  California,  800-533-6887),  or  send  e-mail 
to  linda@ora.com  (uunet!ora!linda). 

For  companies  requiring  extensive  customization  of  the  guide,  source  licensing  terms  are 
also  available. 

xshowfonts.c 


The  source  to  xshowfonts.c , which  is  printed  in  Appendix  E,  is  also  available  free  from 
UUNET  (that  is,  free  except  for  UUNET’s  usual  connect-time  charges).  If  you  have  access 
to  UUNET,  you  can  retrieve  the  source  code  using  uucp  or  ftp.  For  uucp,  find  a machine  with 
direct  access  to  UUNET,  and  type  the  following  command: 

uucp  uunet  \ ! 'uucp/ nutshell/Xuser/ xshowfonts  . c . Z yourhosN.~/yourname/ 

The  backslashes  can  be  omitted  if  you  use  the  Bourne  shell  ( sh ) instead  of  csh.  The  file 
should  appear  some  time  later  (up  to  a day  or  more)  in  the  directory  lusrlspoolluucppub- 
liclyourname. 

To  use  ftp,  ftp  to  uunet.uu.net  and  use  anonymous  as  your  user  name  and  guest  as  your  pass- 
word. Then  type  the  following: 

cd  nutshell/Xuser 

binary  ( you  must  specify  binary  transfer  for  compressed  files) 

get  xshowfonts . c . Z 

bye 

The  file  is  a compressed  C program. 
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Font  and  Character  Conventions 


The  following  typographic  conventions  are  used  in  this  book. 

Italics  are  used  for: 

• new  terms  where  they  are  defined. 

• file  and  directory  names,  and  command  and  client  names  when 
they  appear  in  the  body  of  a paragraph. 

Courier  is  used  within  the  body  of  the  text  to  show: 

• command  lines  or  options  that  should  be  typed  verbatim  on  the 
screen. 

is  used  within  examples  to  show: 

• computer-generated  output. 

• the  contents  of  files. 

Courier  bold  is  used  within  examples  to  show  command  lines  and  options  that 
should  be  typed  verbatim  on  the  screen. 
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Courier  italics  are  used  within  examples  or  explanations  of  command  syntax  to 
show  a parameter  to  a command  that  requres  context-dependent 
substitution  (such  as  a variable).  For  example,  filename  means 
to  use  some  appropriate  filename;  option  (s)  means  to  use  some 
appropriate  option(s)  to  the  command. 

Helvetica  is  used  to  show  menu  titles  and  options. 


The  following  symbols  are  used  within  the  X Window  System  User's  Guide : 

[ ] surround  an  optional  field  in  a command  line  or  file  entry. 

$ is  the  standard  prompt  from  the  Bourne  shell,  sh(\). 

% is  the  standard  prompt  from  the  C shell,  cs/z(l). 

name(  1)  is  a reference  to  a command  called  name  in  Section  1 of  the  UNIX 

Reference  Manual  (which  may  have  a different  name  depending  on 
the  version  of  UNIX  you  use). 
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Part  One: 

Using  X 


Part  One  provides  an  overview  of  the  X Window  System  and  concepts,  and 
describes  how  to  use  the  most  important  programs  available  in  the  X 
environment. 
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An  Introduction  to  the 
X Window  System 

This  chapter  describes  the  features  of  a typical  X display,  while  introducing 
some  basic  window  system  concepts.  It  also  provides  an  overview  of  the  X 
Window  System’s  client-server  architecture  and  briefly  describes  the  most 
commonly  used  clients. 

In  This  Chapter: 

Anatomy  of  an  X Display  5 

X Architecture  Overview  10 

The  X Display  Server 1 1 

Clients  12 

The  Window  Manager 13 

The  xterm  Terminal  Emulator 14 

The  Display  Manager 14 

Other  X Clients  14 

Customizing  Clients  15 
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An  Introduction 
to  the  X Window  System 


The  X Window  System,  called  X for  short,  is  a network-based  graphics  window  system  that 
was  developed  at  MIT  in  1984.  Several  versions  of  X have  been  developed,  the  most  recent 
of  which  is  X Version  11  (XI 1),  first  released  in  1987. 

XI 1 has  been  adopted  as  an  industry-standard  windowing  system.  X is  supported  by  a con- 
sortium of  industry  leaders  such  as  DEC,  Hewlett-Packard,  Sun,  IBM,  and  AT&T  that  have 
united  to  direct,  contribute  to,  and  fund  its  continuing  development.  In  addition  to  the  system 
software  development  directed  by  the  X Consortium,  many  independent  developers  are  pro- 
ducing application  software  specifically  for  use  with  X.  Because  XI 1 is  a relatively  new 
standard,  much  of  this  application  software  has  yet  to  be  released. 

First,  we’ll  take  a look  at  a typical  X display  and  consider  some  general  system  features. 
Then  we’ll  discuss  what  distinguishes  the  X Window  System  from  other  window  systems. 
We’ll  also  briefly  consider  some  of  the  more  important  programs  included  in  the  standard 
distribution  of  X. 


Anatomy  of  an  X Display 

X is  typically  run  on  a workstation  with  a large  screen  (although  it  also  runs  on  PCs  and  spe- 
cial X terminals,  as  well  as  on  many  larger  systems).  X allows  you  to  work  with  multiple 
programs  simultaneously,  each  in  a separate  window.  The  display  in  Figure  1-1  includes  five 
windows. 

The  operations  performed  within  a window  can  vary  greatly,  depending  on  the  type  of  pro- 
gram running  it.  Certain  windows  accept  input  from  the  user,  they  may  function  as  termi- 
nals, allow  you  to  create  graphics,  etc.  Other  windows  simply  display  information,  such  as 
the  time  of  day  or  a picture  of  the  characters  in  a particular  font,  etc. 

The  windows  you  will  probably  use  most  frequently  are  terminal  emulators,  windows  that 
function  as  standard  terminals.  The  terminal  emulator  included  with  the  standard  release  of 
X is  called  xterm.  Figure  1-1  depicts  three  xterm  windows.  In  an  xterm  window,  you  can  do 
anything  you  might  do  in  a regular  terminal:  enter  commands,  run  editing  sessions,  compile 
programs,  etc. 
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Figure  1-1.  X display  with  five  windows  and  an  icon 

The  display  in  Figure  1-1  also  includes  two  other  application  windows:  a clock  (called 
xclock ) and  a calculator  {xcalc). 

The  shaded  area  that  fills  the  entire  screen  is  called  the  root  (or  background)  window.  One  of 
the  strengths  of  a window  system  such  as  X is  that  you  can  have  several  processes  going  on  at 
once  in  several  different  windows  (perhaps  on  different  machines).  For  example,  in  Figure 
1-1,  the  user  is  logging  in  to  a remote  system  in  on  exterm  window  and  is  editing  a text  file  in 
each  of  the  two  other  x term  windows.  (As  we’ll  see  in  Chapter  4,  The  xterm  Terminal  Emula- 
tor,, you  can  also  cut  and  paste  text  between  two  windows.)  Be  aware,  however,  that  you  can 
only  input  to  one  window  at  a time. 

Windows  often  overlap  each  other  much  like  sheets  of  paper  on  your  desk  or  a stack  of  cards. 
Note  that  overlapping  docs  not  interfere  with  the  process  run  in  each  window. 

One  of  the  main  features  of  X is  a type  of  program  called  a window  manager.  The  window 
manager  controls  the  general  operation  of  the  window  system,  allowing  you  to  change  the 
size  and  position  of  windows  on  the  display.  You  can  reshuffle  windows  in  a window  stack, 
make  windows  larger  or  smaller,  move  them  to  other  locations  on  the  screen,  etc.  In  short,  it 
is  the  window  manager  that  controls  the  “look  and  feel”  of  the  X Window  System. 
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In  Release  4,  the  X Consortium  provides  a window  manager  called  twm.  ( twm  originally 
stood  for  “Tom’s  window  manager,”  in  honor  of  its  developer,  Tom  LaStrange.  However,  it 
has  since  been  renamed  the  “tab  window  manager.”  Earlier  releases  supported  a window 
manager  called  uwm,  “universal  window  manager.”)  Notice  that  each  window  on  our  typical 
display  has  a horizontal  bar  that  spans  its  top  edge.  This  feature  is  known  as  a titlebar , 
mainly  because  it  contains  a text  description  of  the  window.  (Generally,  this  is  the  applica- 
tion name,  but  as  we’ll  see  later,  you  can  often  specify  an  alternate  title.)  The  titlebar  is  pro- 
vided by  twm  and  is  one  of  this  window  manager’s  hallmarks. 

In  addition  to  displaying  title  text,  the  titlebar  provides  some  of  the  functionality  of  the  twm 
window  manager.  Using  the  mouse  or  other  pointer  device,  you  can  click  on  various  parts  of 
the  titlebar  to  manipulate  the  window.  Manipulating  a window  with  the  titlebar  is  described 
in  detail  in  Chapter  3,  Using  the  twm  Window  Manager. 

If  you  are  using  another  window  manager,  the  X display  may  have  a different  look  and  feel. 
(Though  you  can  run  a window  system  such  as  X without  a window  manager,  this  severely 
limits  the  system’s  power  and  flexibility,  since  there  is  no  easy  way  to  change  the  size  and 
position  of  windows  on  the  display.) 

Also  pictured  in  Figure  1-1  is  an  icon.  An  icon  is  a small  symbol  that  represents  a window  in 
an  inactive  state.  The  window  manager  allows  you  to  convert  windows  to  icons  and  icons 
back  to  windows.  You  may  want  to  convert  a window  to  an  icon  to  save  space  on  the  display 
or  to  prevent  input  to  that  window.  Each  icon  has  a label,  generally  the  name  of  the  program 
that  created  the  window.  The  icon  in  Figure  1-1  represents  a fourth  xterm  window  on  the 
display.  Icons  can  be  moved  around  on  the  display,  just  like  regular  windows. 

The  contents  of  a window  are  not  visible  when  the  window  has  been  converted  to  an  icon,  but 
they  are  not  lost.  In  fact,  a client  continues  to  run  when  its  window  has  been  iconified;  if  you 
iconify  a terminal  emulator  client,  such  as  xterm , any  programs  running  in  the  shell  will  also 
continue. 

All  X displays  require  you  to  have  some  sort  of  pointer,  often  a three-button  mouse,  with 
which  you  communicate  information  to  the  system.  As  you  slide  the  pointer  around  on  your 
desktop,  a cursor  symbol  on  the  display  follows  the  pointer’s  movement.  For  our  purposes, 
we  will  refer  to  both  the  pointer  device  (e.g.,  a mouse)  and  the  symbol  that  represents  its 
location  on  the  screen  as  pointers.  Depending  on  where  the  pointer  is  on  the  screen  (in  an 
xterm  window,  in  another  replication  window,  on  the  root  window,  etc.),  it  is  represented  by 
a variety  of  cursor  symbols.  If  the  pointer  is  positioned  on  the  root  window,  it  is  generally 
represented  by  an  X-shaped  cursor,  as  in  Figure  1-1.  If  the  pointer  is  in  an  xterm  window,  it 
looks  like  an  “I”  and  is  commonly  called  an  I-beam  cursor* 

A complete  list  of  cursors  is  shown  in  Appendix  D,  Standard  Cursors.  Some  of  the  most 
common  cursor  shapes  are  shown  in  Figure  1-2.  As  we’ll  see  later,  some  applications  allow 
you  to  select  the  cursor  to  use. 


♦Even  though  the  actual  image  on  the  screen  is  called  a cursor,  throughout  this  guide  we  refer  to  “moving  the  point- 
er” to  avoid  confusion  with  the  standard  text  cursor  that  can  appear  in  an  xterm  window. 
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X cursor  which  appears  in  the  root  window. 


I-beam  cursor,  which  appears  within  xterm 
windows. 


Menu  arrow  cursor,  which  points  at  menu  items 
currently  selected. 


Upper  left  and  lower  right  corner  cursors, 
which  allow  interactive  placement  of  client 
windows  when  using  twm. 


Filled  circle,  which  allows  targeting  of  window  to 
be  acted  on  by  twm  for  certain  functions  (setting 
focus,  raising,  lowering,  etc.) 

Cross  cursor,  which  is  used  to  resize  and  move 
windows  via  twm. 

Skull  and  crossbones  cursor,  which  is  used  to 
select  the  window  to  be  removed  with  the  Delete 
and  Kill  commands  on  the  Twm  menu. 


Figure  1-2.  Some  standard  cursors 

You  use  the  pointer  to  manipulate  windows  and  icons,  to  make  selections  in  menus,  and  to 
select  the  window  in  which  you  want  to  input.  You  can’t  type  in  an  xterm  window  unless  you 
place  the  pointer  in  that  window,  as  in  Figure  1-3. 

Directing  input  to  a particular  window  is  called  focusing.  You  must  be  sure  that  the  pointer 
rests  in  the  desired  window  before  you  begin  typing.  The  window  border  (if  present)  and  text 
cursor  are  also  highlighted  when  the  pointer  is  in  that  window.  The  highlighting  is  a charac- 
teristic of  xterm : other  applications  may  not  highlight  display  features. 

The  fact  that  input  focus  automatically  follows  the  pointer  is  a default  characteristic  of  the 
twm  window  manager.  Other  window  managers  require  you  to  click  on  a window  to  focus 
input  on  that  window.  These  two  window  manager  focusing  styles  are  commonly  referred  to 
as  “real-estate-driven”  (or  “pointer  focus”)  and  “click-to-type.” 

The  most  important  thing  to  recognize  is  that  the  position  of  the  pointer  is  very  important  to  a 
real-estate-driven  window  manager  like  twm.  If  something  doesn’t  work  the  way  you  expect, 
make  sure  that  the  pointer  is  in  the  right  place.  After  you  use  X for  a while,  awareness  of 
pointer  position  will  come  naturally. 

Be  aware  that  it  may  take  a moment  for  the  input  focus  to  catch  up  with  the  pointer,  espe- 
cially on  slower  machines.  If  you  type  right  away,  some  keystrokes  may  end  up  in  the  win- 
dow you  left  rather  than  in  the  new  window.  This  is  really  a bug  and  happens  because  of  the 
additional  overhead  involved  in  complex  window  managers  like  twm  or  mwm.  It  doesn’t 
happen  if  you  are  using  a simpler  window  manager  like  uwm. 


* 
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Figure  1-3.  Focus  on  an  xterm  window 

The  pointer  is  also  often  used  to  display  menus.  Some  X programs,  notably  twm  and  xterm , 
have  menus  that  are  displayed  by  keystrokes  and/or  pointer  button  motions.  Unlike  some 
window  systems,  which  allow  you  to  “pull  down”  menus  from  a menu  bar  that  is  always 
displayed,  twm  (and  most  X clients)  support  “pop-up”  menus,  which  are  displayed  at  the  cur- 
rent pointer  position.  In  addition  to  keyboard  keys  and  pointer  button  motions,  the  location 
of  the  pointer  also  plays  a role  in  displaying  menus.  For  example,  xterm  menus  can  only  be 
displayed  when  the  pointer  is  within  an  xterm  window.  Figure  1-4  shows  a twm  menu  called 
Twm,  which  is  displayed  by  placing  the  pointer  on  the  root  window  and  holding  down  the 
first  pointer  button. 

You  generally  display  this  menu  by  moving  the  pointer  to  the  root  window  and  pressing  and 
holding  down  the  first  pointer  button.  In  Figure  1-4,  the  arrow  next  to  the  menu  title  repre- 
sents the  pointer.  As  you  drag  the  pointer  down  the  menu,  each  of  the  menu  selections  is 
highlighted.  Regardless  of  the  program,  you  generally  select  a menu  item  by  dragging  the 
pointer  down  the  menu,  highlighting  the  item  you  want,  and  releasing  the  pointer  button. 

With  other  programs,  particularly  several  oilier  window  managers,  you  can  display  a menu 
simply  by  placing  the  pointer  on  a particular  part  of  the  window,  e.g.,  a horizontal  bar  across 
the  top. 

A final  note  about  the  X display:  in  X,  the  terms  display  and  screen  are  not  equivalent.  A 
display  may  consist  of  more  than  one  screen.  This  feature  might  be  implemented  in  several 
ways.  There  might  be  two  physical  monitors,  linked  to  form  a single  display,  as  shown  in 
Figure  1-5.  Alternatively,  two  screens  might  be  defined  as  different  ways  of  using  the  same 
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Figure  1-4.  Twm  menu  on  the  root  window 


display.  For  example,  on  ihe  Sun-3/110  color  workstation,  screen  0 is  black  and  white,  and 
screen  1 is  color.  By  default,  windows  are  always  placed  on  screen  0,  but  you  can  “scroll” 
between  the  two  screens  with  the  mouse,  or  place  a client  window  on  screen  1 by  specifying 
the  screen  number  in  the  -display  option  when  starting  the  client.  (See  Chapter  8,  Com- 
mand Line  Options,  for  more  information  on  the  -display  option.) 


X Architecture  Overview 

Most  window  systems  are  kernel-based : that  is,  they  are  closely  tied  to  the  operating  system 
itself  and  can  only  run  on  a discrete  system,  such  as  a single  workstation.  The  X Window 
System  is  not  part  of  any  operating  system  but  is  instead  comprised  entirely  of  “user-level” 
programs. 

The  architecture  of  the  X Window  System  is  based  on  what  is  known  as  a client-server 
model.  The  system  is  divided  into  two  distinct  parts:  display  servers  that  provide  display 
capabilities  and  keep  track  of  user  input,  and  clients,  application  programs  that  perform  spe- 
cific tasks.  On  a more  basic  level,  the  server  acts  as  an  intermediary  between  client  applica- 
tion programs  and  the  local  display  hardware.  The  client  programs  make  requests  (for  infor- 
mation, processes,  etc.)  that  are  communicated  to  the  hardware  display  by  the  server. 
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This  division  within  the  X architecture  allows  the  clients  and  the  display  server  either  to 
work  together  on  the  same  machine  or  to  reside  on  different  machines  (possibly  of  different 
types,  with  different  operating  systems,  etc.)  that  arc  connected  by  a network.  For  example, 
you  might  use  a relatively  low-powered  PC  or  workstation  as  a display  server  to  interact  with 
clients  that  arc  running  on  a more  powerful  remote  system.  Even  though  the  client  program 
is  actually  running  on  the  more  powerful  system,  all  user  input  and  displayed  output  occur  on 
the  PC  or  workstation  server  and  are  communicated  across  the  network  using  the  X protocol 
Figure  1-6  shows  a diagram  of  such  a network. 

There  is  another  less  obvious  advantage  to  the  client-server  model:  since  the  server  is 
entirely  responsible  for  interacting  with  the  hardware,  only  the  server  program  must  be 
machine-specific.  X client  application  programs  can  be  ported  easily  from  system  to  system. 


The  X Display  Server 

The  X display  server  is  a program  that  keeps  track  of  all  input  coming  from  input  devices, 
such  as  the  keyboard  and  mouse,  and  input  from  any  oilier  clients  that  are  running.  As  the 
display  server  receives  information  from  a client,  it  updates  the  appropriate  window  on  your 
display.  The  display  server  may  run  on  the  same  computer  as  a client  or  on  an  entirely  differ- 
ent machine. 

Servers  are  available  for  PCs,  workstations,  and  even  for  special  terminals,  which  may  have 
the  server  downloaded  from  another  machine  or  stored  in  ROM. 
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Figure  1-6.  A sample  X Window  System  configuration 

Clients 


X allows  you  to  run  many  clients  simultaneously.  For  example,  you  could  be  editing  a text 
file  in  one  window,  compiling  a program  source  file  in  a second  window,  reading  your  mail  in 
a third,  all  the  while  displaying  the  system  load  average  in  a fourth  window. 

While  X clients  may  display  their  results  and  take  input  from  a single  display  server,  they 
may  each  be  running  on  a different  computer  on  the  network.  It  is  important  to  note  that  the 
same  programs  may  not  look  and  act  the  same  on  different  servers  since  there  is  no  standard 
user  interface,  since  users  can  customize  X clients  differently  on  each  server,  and  since  the 
display  hardware  on  each  server  may  be  different. 

Several  of  the  more  frequently  used  client  programs  are  discussed  in  the  following 
paragraphs. 
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The  Window  Manager 


The  way  a kernel-based  window  system  operates  is  inherent  in  the  window  system  itself.  By 
contrast,  the  X Window  System  concentrates  control  in  a window  manager,  several  of  which 
are  available.  The  window  manager  you  use  largely  determines  the  look  and  feel  of  X on  a 
particular  system. 

The  window  manager  shipped  with  the  standard  release  of  X from  MIT  is  called  twm.  As 
we’ve  discussed,  twm  allows  you  to  move  and  resize  windows,  rearrange  the  order  of  win- 
dows in  the  window  stack,  create  additional  windows,  and  convert  windows  into  icons,  etc. 
These  functions  are  discussed  more  fully  in  Chapter  2,  Getting  Started,  and  Chapter  3,  Using 
the  twm  Window  Manager . 

Prior  to  Release  4,  the  standard  window  manager  shipped  with  X was  uwm,  the  universal 
window  manager,  uwm  has  been  superceded  by  twm  because  the  latter  has  been  made  com- 
pliant with  the  X Consortium’s  Inter-Client  Communication  Conventions  Manual  (ICCCM), 
introduced  at  Release  3. 

The  ICCCM  contains  standards  for  interaction  with  window  managers  and  other  clients.  It 
defines  basic  policy  intentionally  omitted  from  X itself,  such  as  the  rules  for  transferring  data 
between  applications,  for  transferring  keyboard  focus,  for  installing  colormaps,  and  so  on. 
As  long  as  applications  and  window  managers  follow  the  conventions  outlined  in  the 
ICCCM,  applications  created  with  different  toolkits  will  be  able  to  coexist  and  work  together 
on  the  same  server. 

Because  uwm  does  not  comply  with  the  standards  outlined  in  the  ICCCM,  it  has  been  moved 
to  a directory  of  user-contributed  clients  in  Release  4,  where  it  is  still  available  for  those  who 
wish  to  use  it.  However,  uwm  is  no  longer  officially  supported  by  the  X Consortium,  and  it 
should  probably  not  be  the  window  manager  of  choice.  If  you  are  still  using  uwm.  Appendix 
B,  The  uwm  Window  Manager,  discusses  getting  started  with  and  customizing  this  window 
manager. 

In  this  guide,  we  assume  you  are  using  twm.  Several  other  window  managers,  such  as  mwm 
(the  Motif™  window  manager),  awm  (Ardent™  window  manager),  rtl  (tiled  window  man- 
ager, developed  at  Siemens  Research  and  Technology  Laboratories,  RTL),  and  olwm  (the 
OPENLOOK™  window  manager)  are  also  widely  used. 

mwm  is  discussed  in  greater  detail  in  Appendix  C,  The  OSF/Motif  Window  Manager. 

If  the  twm  window  manager  has  been  customized  at  your  site  or  you  are  using  a different 
window  manager,  many  of  the  concepts  should  still  be  the  same.  However,  the  actual  proce- 
dures shown  may  well  differ.  See  Chapter  10,  Customizing  the  twm  Window  Manager,  for  a 
discussion  of  how  to  customize  twm. 
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The  xterm  Terminal  Emulator 


XI 1 itself  is  designed  to  support  only  bitmapped  graphics  displays.  For  this  reason,  one  of 
the  most  important  clients  is  a terminal  emulator.  The  terminal  emulator  brings  up  a window 
that  allows  you  to  log  in  to  a multiuser  system  and  to  run  applications  designed  for  use  on  a 
standard  alphanumeric  terminal.  Anything  you  can  do  on  a terminal,  you  can  do  in  this  win- 
dow. 

xterm  is  the  most  widely  available  terminal  emulator,  xterm  emulates  a DEC®  VT102  termi- 
nal or  a Tektronix®  4014  terminal.  You  can  display  both  types  of  windows  at  the  same  time, 
but  only  one  is  active  at  a time. 

Since  you  can  bring  up  more  than  one  xterm  window  at  a time,  you  can  run  several  programs 
at  once.  For  example,  you  can  have  the  system  transfer  files  or  process  information  while 
you  focus  your  attention  on  a text-editing  session.  Multiple  xterm  processes  allow  you  to  dis- 
play interactions  in  separate  windows  on  your  screen.  See  Chapter  2,  Getting  Started , and 
Chapter  4,  The  xterm  Terminal  Emulator , for  additional  information. 


The  Display  Manager 


The  display  manager,  xdm,  is  a client  that  is  designed  to  start  the  X server  automatically 
(from  the  UNIX  letclrc  system  startup  file)  and  to  keep  it  running.  (X  can  also  be  started 
manually,  as  described  in  Chapter  2.)  In  its  most  basic  implementation,  the  display  manager 
emulates  the  getty  and  login  programs,  which  put  up  the  login  prompt  on  a standard  terminal, 
keeping  the  server  running,  prompting  for  a user’s  name  and  password,  and  managing  a stan- 
dard login  session. 

However,  xdm  has  far  more  powerful  and  versatile  capabilities.  Users  can  design  their  own 
sessions,  running  several  clients  and  setting  personal  resources  (such  as  keyboard,  pointer, 
and  display  characteristics).  You  can  also  customize  special  x dm  files  to  manage  several  con- 
nected displays  (both  local  and  remote)  and  to  set  system-wide  X resources  (for  example,  cli- 
ent default  features).  Resources  are  discussed  in  Chapter  9,  Setting  Resources.  See  Appen- 
dix A,  System  Management , for  a discussion  of  how  to  set  up  and  customize  the  display  man- 
ager. 


Other  X Clients 


The  following  is  a brief  list  of  some  other  clients  commonly  included  with  X. 


xclock 

bitmap 

xcalc 

xset 

xwd 


Displays  the  time  of  day  continuously  either  in  digital  or  in  analog  form. 
Allows  you  to  change  your  pointers,  icons,  and  background  window  pattern. 
Provides  a scientific  calculator  on  your  display. 

Allows  you  to  set  various  display  and  keyboard  preferences,  such  as  bell  vol- 
ume, cursor  acceleration,  screen  saver  operation,  and  so  on. 

Dumps  the  contents  of  a window  into  a file. 
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xpr 


Translates  an  image  file  produced  by  xwd  to  PostScript®  or  other  formats, 
suitable  for  printing  on  a variety  of  printers. 

xfd  Displays  the  contents  of  a font  on  the  screen. 

For  additional  information  on  these  and  other  clients,  refer  to  Chapter  5,  Font  Specification , 
Chapter  6,  Graphics  Utilities,  Chapter  7,  Other  Clients,  Chapter  11 , Setup  Clients,  and  to  the 
reference  page  for  each  client  in  Part  Three  of  this  guide.  As  more  commercial  and  user- 
contributed  software  is  developed,  many  more  specialized  programs  will  become  available. 


Customizing  Clients 

Most  X clients  are  designed  to  be  customized  by  the  user.  A multitude  of  command  line 
options  can  be  used  to  affect  the  operation  of  these  clients.  More  conveniently,  default  val- 
ues for  each  option  can  be  stored  in  a file  (generally  called  Xresources  or  Xdefaults ) in  your 
home  directory.  If  you  are  running  clients  on  multiple  machines,  a program  called  xrdb  (X 
resource  database  manager)  should  be  used  to  store  your  defaults  in  the  server  so  that  you 
don’t  need  to  maintain  an  Xdefaults  file  on  each  machine. 

There  is  a separate  customization  file  for  the  twm  window  manager,  called  .twmrc,  which  is 
also  kept  in  your  home  directory. 

Client  customization  is  described  in  Part  Two  of  this  guide. 


An  Introduction  to  the  X Window  System 


15 


— 

2 


Getting  Started 

This  chapter  shows  you  how  to  begin  working  if  X is  already  running  on  your 
system  and  how  to  start  the  X server  manually  if  X is  not  running.  It  also  pro- 
vides preliminary  instructions  for  starting  the  window  manager,  twm,  and  the 
xterm  terminal  emulator. 

In  This  Chapter: 

If  X is  Being  Started  Automatically  19 

Starting  X Manually  22 

Starting  the  First  xterm  Window 22 

Bringing  Up  the  Window  Manager 23 

Starting  a Second  xterm  Window 23 

Exiting  from  an  xterm  Window  25 

Special  Keys 26 

How  a Client  Looks  and  Behaves:  Application  Defaults 26 

Starting  Other  Clients  27 

Running  a Client  on  Another  Machine  28 

Where  to  Go  From  Here  30 
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Getting  Started 


This  chapter  introduces  the  basics  of  using  X:  starting  the  server  and  creating  the  first  termi- 
nal window;  starting  the  window  manager;  adding  additional  windows;  exiting.  While  it  is 
written  as  a tutorial,  you  do  not  necessarily  have  to  follow  along  at  a workstation. 

Before  you  can  begin  using  the  X Window  System,  you  must  do  three  things: 

• Start  the  X server. 

• Start  at  least  one  instance  of  the  xterm  terminal  emulator. 

• Start  a window  manager.  (Though  you  can  run  X without  a window  manager,  this  is  fair- 
ly limiting.) 

Depending  on  how  X is  configured  on  your  system,  some  or  all  of  these  steps  may  be  per- 
formed for  you  automatically.  First,  this  chapter  explains  how  you  can  tell  if  X is  being  start- 
ed automatically  and  how  to  begin  working  if  it  is.  Then  this  chapter  describes  how  to  start 
X manually.  Later  sections  show  you  how  to  exit  from  an  xterm  window  and  how  to  start  ad- 
ditional client  programs. 


If  X is  Being  Started  Automatically 

Depending  on  how  X is  being  run  on  your  system,  the  initial  screens  you  see  and  the  way  you 
log  in  will  be  slightly  different. 

If  you  log  in  at  a prompt  displayed  on  the  full  screen,  your  workstation  may  automatically 
start  the  server  and  open  up  the  first  xterm  window.  If  this  is  the  case,  your  screen  should 
then  look  something  like  Figure  2-1. 
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Figure  2-1.  Workstation  with  login  xterm  window  on  the  root  window 


If  the  display  manager,  xdm,  is  running  X on  your  system,  you  may  see  a window  similar  to 
Figure  2-2  when  you  turn  on  your  terminal. 

Log  in  just  as  if  you  were  using  a standard  alphanumeric  terminal.  The  screen  should  then 
display  the  first  xterm  window,  as  in  Figure  2-1. 

Without  any  user  customization,  the  display  manager  executes  a standard  login  “session,” 
providing  the  first  xterm  window  and  starting  the  window  manager.  If  the  window  manager 
is  running,  you  will  see  a titlebar  on  your  window,  displaying  the  name  of  the  window 
(“xterm”). 

If  the  twm  window  manager  is  running,  skip  to  the  section  “Starting  a Second  xterm  Win- 
dow” later  in  this  chapter  for  information  on  starting  additional  windows  and  other  clients.  If 
the  window  manager  is  not  running,  skip  to  the  section  “Bringing  Up  the  Window  Manager” 
later  in  this  chapter  for  instruction  on  how  to  start  it. 

On  BSD  4.3  systems,  there  is  another  method  to  bring  up  X automatically  (from  the  /etc/ttys 
system  file).  This  method  has  been  phased  out  in  Release  4.  However,  if  your  system  is  set 
up  to  use  this  method,  when  the  power  is  turned  on,  your  workstation  should  automatically 
start  the  server  and  open  up  an  x term  window  in  which  you  can  log  in.  If  this  is  the  case, 
your  screen  should  look  something  like  Figure  2-3. 
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Figure  2-2.  xdm  login  window 


\ 


Figure  2-3.  xterm  window  with  login  prompt 
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Log  in  by  typing  your  name  and  password  at  the  prompts  in  the  x term  window,  just  as  if  you 
were  using  a standard  alphanumeric  terminal.  Skip  to  the  section  “Bringing  Up  the  Window 
Manager”  later  in  this  chapter. 


Starting  X Manually 

If  no  windows  are  displayed  on  the  workstation  screen  (i.e.,  if  your  login  prompt  appears  on 
the  full  screen),  log  in,  and  read  on.  If  another  windowing  system  (such  as  SunView™)  is 
running,  first  kill  it,  and  then  read  on. 

To  start  X manually  (using  the  standard  X distribution  from  MIT),  you  must  run  two  separate 
programs  to  perform  the  three  steps  listed  at  the  beginning  of  the  chapter: 

% xinit  To  start  the  X server  and  create  the  first  (login)  x term  window. 

% twin  & To  start  the  window  manager. 

In  the  following  discussion,  we’ll  assume  that  you  are  bringing  up  the  X Window  System 
manually.  In  Appendix  A,  System  Management,  we’ll  show  you  how  to  set  things  up  so  that 
X comes  up  automatically. 

X is  very  easy  to  customize.  There  are  countless  command  options  as  well  as  startup  files 
that  control  the  way  the  screen  looks  or  even  what  menus  a program  displays.  If  you  are  “try- 
ing out”  X using  someone  else’s  system  or  login  account,  things  may  not  work  as  described 
here.  (See  Chapters  8 through  1 1 for  information  on  customizing  the  X environment.) 


Starting  the  First  xterm  Window 

First,  make  sure  that  the  XI 1 directory  containing  executable  programs  is  in  your  search 
path.*  If  not,  add  the  pathname  lusrlbin/Xll  to  the  path  set  in  your  .profile  or  .login  file. 
Then  at  the  prompt,  type: 

% xinit 

xinit  starts  the  X server  and  creates  the  first  xterm  window  in  the  upper-left  comer  of  your 
display.! 

*For  more  information  on  how  to  set  your  search  path,  see  Appendix  A.  Note  that  the  appropriate  pathname  to  add 
may  be  different  in  vendor  distributions. 

flf  xinit  produces  a blank  background,  with  no  terminal  window,  software  installation  was  not  completed  correctly. 
Reboot  your  workstation  and  try  again.  Before  invoking  xinit,  look  in  the  directory  lusrlbin/Xll  for  a file  whose 
name  begins  with  a capital  X but  otherwise  has  a similar  name  to  your  workstation  (e.g.,  Xsun).  When  you  find  one 
that  seems  a likely  possibility,  try  the  following  command: 

% xinit  --  Xname 

If  that  works,  link  Xname  to  X,  and  xinit  will  thereafter  work  correctly.  For  example: 

% cd  /usr/bin/Xll 
% In  Xsun  X 
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Bringing  Up  the  Window  Manager 


Make  sure  that  the  pointer  is  in  the  xterm  window,  so  that  the  I-beam  cursor  is  displayed. 
Start  the  twm  window  manager  by  typing: 

% twm  & 

The  screen  will  momentarily  go  blank;  then  the  window  will  be  redisplayed,  this  time  with  a 
titlebar.  The  titlebar  provides  a quick  and  easy  way  to  move,  resize,  and  otherwise  manipu- 
late windows  on  the  screen.  The  window  manager  also  allows  you  to  position  client  win- 
dows on  the  screen,  as  illustrated  by  the  placement  of  the  xterm  window  described  in  the  next 
section. 

Note  that  it  is  important  to  run  twm  in  the  background  by  placing  an  ampersand  (&)  at  the 
end  of  the  command  line,  so  that  you  can  continue  to  enter  additional  commands  into  the 
xterm  window.  If  you  neglected  to  do  this  on  a system  that  supports  job  control,  type 
Control-Z  to  suspend  twm,  then  use  the  bg  command  (see  csh(  1))  to  place  it  in  the  back- 
ground. 

If  the  system  you’re  on  does  not  support  job  control,  interrupt  the  process  with  Delete  or 
Control-C  and  start  over. 


Starting  a Second  xterm  Window 

If  you  want  to  open  a second  xterm  window,  type  the  following  command  at  the  prompt  in 
the  first  xterm  window: 

% xterm  & 

After  a few  moments,  the  pointer  becomes  an  upper-left-comer  cursor,  as  shown  in  Figure 
2-4. 

This  comer  cursor  represents  the  upper-left  comer  of  the  window  you  want  to  place.  The 
cursor  tracks  pointer  movement  as  you  move  the  pointer  across  your  screen  and  allows  you  to 
position  the  xterm  window. 

Move  the  comer  cursor  to  the  desired  position  on  your  screen  and  click  the  left  mouse  button. 
(A  click  is  defined  as  pressing  the  mouse  button  down  and  releasing  it.)  A new  xterm  win- 
dow appears  on  your  screen,  with  a prompt  from  whatever  shell  you  are  using.  Figure  2-5 
shows  how  your  screen  might  look  now. 
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Figure  2-4.  Placing  a second  xterm  window 


Figure  2-5.  Two  xterm  windows 
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You  can  switch  back  and  forth  between  windows  simply  by  moving  the  pointer  from  one  to 
the  other. 

If  you  have  inadvertently  positioned  the  second  xterm  window  in  front  of  the  first  one,  don’t 
be  concerned.  Just  use  the  front  window  for  now.  Chapter  3,  Using  the  twm  Window  Manag- 
er, provides  information  on  resizing  and  moving  windows. 

Notice  how  the  text  cursor,  titlebar,  and  border  in  each  xterm  window  are  highlighted  when 
you  move  the  pointer  into  that  window.  Whatever  you  type  will  appear  in  the  window  with 
the  highlighted  titlebar.  Try  starting  a command  in  both  windows.  For  example,  start  up  vi  or 
another  text  editor  in  the  second  x term  window.  Notice  how  you  can  switch  back  to  the  first 
window  to  type  a new  command,  simply  by  moving  the  pointer — even  if  you  leave  vi  in  in- 
sert mode  or  some  other  command  in  the  process  of  sending  output  to  the  screen.  Whatever 
process  was  running  in  the  window  you  left  will  continue  to  run.  If  it  needs  input  from  you  to 
continue,  it  will  wait. 


Exiting  from  an  xterm  Window 

When  you  are  through  using  an  xterm  window,  you  can  remove  it  by  typing  whatever  com- 
mand you  usually  use  to  log  off  your  system.  Typically,  this  might  be  exit  or  Control-D. 
You  can  also  terminate  an  xterm  window  by  selecting  Hangup,  Terminate,  Kill,  or  Quit  from 
the  xterm  menu.  (These  menu  options  send  different  signals  to  the  xterm  process.  Depending 
on  what  signals  your  operating  system  recognizes,  some  of  the  options  may  not  work  as  in- 
tended. See  Chapter  4,  The  xterm  Terminal  Emulator,  for  more  information.) 

Be  aware  that  terminating  the  login  xterm  window  (the  first  xterm  to  appear)  kills  the  X 
server  and  all  associated  clients.  (If  xdm  is  running  X,  the  server  will  be  reset,  but  only  after 
all  client  processes  have  been  killed.)  Be  sure  to  terminate  all  other  xterm  windows  before 
terminating  the  xterm  login  window.  Also,  be  sure  that  if  you  are  in  an  editor  such  as  vi  that 
you  save  your  data  before  you  terminate  the  window 

In  fact,  it  may  be  wise  to  iconify  the  login  window  (shrink  it  into  a small  symbol,  or  icon,  on 
the  screen)  and  use  other  xterm  windows  instead,  so  that  you  don’t  inadvertently  terminate  it. 
See  Chapter  3,  Using  the  twm  Window  Manager,  for  a discussion  of  how  to  do  this. 

Alternatively,  you  can  enter: 

% sot  ignorooof 

in  the  login  window.  Then  typing  exit  becomes  the  only  way  you  can  terminate  the  win- 
dow. Note  that  some  C shell  implementations  have  an  autologout  variable,  which  will  auto- 
matically terminate  the  shell  if  there  is  no  activity  for  a given  period  of  time. 

If  your  C shell  supports  this  feature,  be  sure  to  disable  it  in  the  login  xterm  window  using  the 
following  command: 

% unset  autologout 
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Special  Keys 


Most  workstations  have  a number  of  “modifier”  keys,  so  called  because  they  modify  the  ac- 
tion of  other  keys. 

Three  of  these  modifier  keys  should  be  familiar  to  any  user  of  a standard  ASCII  terminal  or 
personal  computer — Shift,  Caps  Lock,  and  Control.  However,  many  workstations  have  addi- 
tional modifier  keys  as  well.  A PC  has  an  “Alt”  key,  a Macintosh™  has  a “fan”  key,  a Sony 
workstation  has  keys  named  “Nfer”  and  “Xfer,”  and  a Sun  workstation  has  no  less  than  three 
additional  modifier  keys,  labeled  “Left,”  “Right,”  and  “Alternate.” 

Because  X clients  are  designed  to  run  on  many  different  workstations,  with  different  key- 
boards, it  is  difficult  to  assign  functions  to  special  keys  on  the  keyboard.  A developer  can’t 
count  on  the  same  key  always  being  present! 

For  this  reason,  many  X clients  make  use  of  “logical”  modifier  keynames,  which  can  be 
mapped  by  the  user  to  any  actual  key  on  the  keyboard. 

Up  to  eight  separate  modifier  keys  can  be  defined.  The  most  commonly  used  (after  Shift, 
Caps  Lock,  and  Control)  has  the  logical  keyname  “Meta.” 

We’ll  talk  at  length  about  this  subject  in  Chapter  11,  Setup  Clients,  but  we  wanted  to  warn 
you  here.  When  we  talk  later  in  this  book  about  pressing  the  “Meta”  key,  you  should  be 
aware  that  there  is  not  likely  to  be  a physical  key  on  the  keyboard  with  that  name.  For  ex- 
ample, on  one  workstation,  the  Meta  key  might  be  labeled  “Alt”  and,  on  another,  “Fund.” 
And  as  we’ll  show  in  Chapter  11,  you  can  choose  any  key  you  want  to  act  as  the  Meta  key. 

Unfortunately,  X provides  no  easy  way  to  find  out  which  key  on  your  keyboard  has  been  as- 
signed to  be  the  Meta  key.  You  don’t  need  to  know  this  right  away . . .but  when  you  do, 
please  turn  to  the  discussion  of  key  mapping  in  Chapter  1 1,  Setup  Clients,  for  information  on 
how  you  can  find  out. 


How  a Client  Looks  and  Behaves:  Application  Defaults 

The  way  the  xterm  client  looks  (and,  to  some  extent,  behaves)  is  partially  determined  by  a 
system-wide  file  of  application  defaults.  Several  clients  have  application  defaults  files  that 
determine  certain  of  the  client’s  features.  Applications  defaults  files  generally  reside  in  the 
directory  lusrlliblXlllapp-defaults  and  are  named  for  the  client  application.  For  xterm,  the 
application  defaults  specify  such  things  as  the  labels  for  menu  items,  the  fonts  used  to  display 
menu  items,  and  the  shape  of  the  pointer  when  it’s  in  an  xterm  window. 

In  describing  the  appearance  and  behavior  of  clients  in  this  guide,  we  assume  all  of  the  stan- 
dard application  defaults  file  are  present  on  your  system  and  accessible  by  the  client  pro- 
grams. If,  by  some  chance,  a client’s  application  defaults  file  has  been  edited  or  removed 
from  your  system,  the  client  may  not  look  or  behave  exactly  as  we  describe  it  If  a client  ap- 
plication appears  substantially  different  than  it  is  depicted  in  this  guide,  you  may  be  using  a 
different  version  of  the  program  or  the  application  defaults  may  be  different.  Consult  your 
system  administrator. 
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Within  an  application  defaults  file,  defaults  are  set  using  variables  called  resources.  Almost 
every  feature  of  every  client  program  can  be  controlled  by  a resource  variable.  The  resource 
variables  specified  in  a client’s  application  defaults  files  are  usually  just  a subset  of  a greater 
number  of  resources  that  can  be  set 

As  we’ll  see  in  Chapter  9,  Setting  Resources , you  can  override  the  system-wide  defaults  and 
control  additional  features  of  a client  by  specifying  your  own  resources  in  a file  in  your  home 
directory. 


Starting  Other  Clients 

You  can  start  other  X clients  just  like  you  can  start  another  instance  of  xterm.  At  the  com- 
mand line  prompt  in  any  xterm  window,  type  the  name  of  the  client  followed  by  an  amper- 
sand to  make  the  client  run  in  the  background.  For  example,  by  typing: 

% oclock  & 

you  can  cause  a window  displaying  a clock  to  be  placed  on  the  screen.  (The  oclock  client  is 
available  as  of  Release  4.  If  you  are  running  an  earlier  release  of  X,  the  only  clock  program 
available  is  xclock.)  First  an  upper-left  comer  cursor  will  appear,  just  as  it  did  when  you 
created  a second  xterm  window.  Move  the  comer  cursor  to  the  position  you  would  like  the 
clock  to  appear,  and  then  click  the  left  mouse  button.  Figure  2-6  shows  the  oclock  display, 
placed  in  the  upper-right  comer  of  the  screen. 

Unfortunately,  the  developers  of  oclock  neglected  to  provide  an  easy  way  to  remove  it.  One 
way  to  remove  the  oclock  display  is  to  identify  and  kill  the  process  using  the  standard  UNIX 
process  control  mechanisms.  To  find  the  process  ID  for  oclock , go  to  an  xterm  window  and 
type: 

% pa  -aux  | grep  oclock 
at  a system  prompt.  Under  System  V,  type: 

% pa  -a  | grep  oclock 

at  a system  prompt.  The  resulting  display  should  look  something  like  this: 

128  pO  0:00  oclock 
142  pO  0:00  grep  oclock 

The  number  in  the  first  column  is  the  process  ID.  Type: 

% kill  process  jd 

The  oclock  display  will  be  removed,  and  you  will  get  the  message: 

Terminated  oclock 

You  can  also  remove  the  oclock  display  using  other  methods  intended  to  “kill”  the  client  pro- 
cess. These  methods  and  their  liabilities  are  discussed  in  Chapter  7,  Other  Clients. 

If  you  are  running  Release  2 or  3 of  X,  the  x clock  client  must  also  be  removed  using  the 
UNIX  kill  command  (or  another  method  of  killing  a client,  as  described  in  Chapter  7).  As  of 
Release  4,  xclock  can  also  be  removed  by  a gentler  method,  namely,  the  Delete  item  of  the 
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Figure  2-6.  The  oclock  display 

Twm  menu.  See  Chapter  3,  Using  the  twm  Window  Manager,  for  more  information  about  De- 
lete. 


Running  a Client  on  Another  Machine 

Remember  that  X also  allows  you  to  run  a client  on  another  machine,  while  displaying  the 
client’s  window  on  the  local  machine.  A client  you  may  wish  to  run  on  another  machine  is 
xload,  which  is  used  to  keep  track  of  the  system  load  average.  By  default,  xload  polls  the 
system  for  the  load  average  at  five-second  intervals  and  displays  the  results  in  a simple  histo- 
gram. 

If  you  are  running  processes  on  more  than  one  machine,  it’s  useful  to  gauge  the  level  of  ac- 
tivity on  the  systems  in  question.  This  information  should  help  you  judge  when  to  start 
processes  and  monitor  how  your  processes  are  impacting  system  resources. 

Say  you’re  running  clients  both  on  the  local  machine  (let’s  call  it  hostl)  and  on  another 
machine  ( host2 ).  On  the  local  display,  you  can  have  two  xload  windows,  one  showing  activ- 
ity on  hostl  and  one  showing  activity  on  host2. 

To  create  an  xload  window  monitoring  activity  on  hostl , use  the  command: 

% xload  & 
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The  cursor  changes  to  an  upper-left  comer  cursor,  allowing  you  to  place  the  window. 

Then  run  an  x load  process  on  host!  using  a remote  shell  ( rsh ),  and  display  the  results  in  a 
window  on  hostl : 

% rsh  host  2 ' xload  -display  hostl :0'  & 

Again,  you  place  the  window  using  the  pointer. 

The  -display  option  tells  xload  to  create  its  window  on  the  local  display  (hostl).  The 
syntax  and  use  of  this  option  is  discussed  more  fully  in  Chapter  8,  Command  Line  Options. 

Figure  2-7  shows  the  resulting  hostl  display:  two  xload  windows,  the  top  window  monitor- 
ing activity  on  the  local  system  and  the  bottom  one  monitoring  activity  on  the  remote  system. 
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Figure  2-7.  Monitoring  activity  on  two  systems  with  xload 


If  you  frequently  need  to  access  a remote  system,  you  may  want  to  run  an  xterm  on  that  sys- 
tem using  a remote  shell  and  display  the  window  on  the  local  system.  For  instance,  the  fol- 
lowing command  runs  an  x term  on  a remote  Sony  NEWS  workstation  (with  the  hostname 
sony)  and  displays  on  the  local  Sun-3  (with  the  hostname  sun): 

% rsh  sony  'xtarm  -display  sun:0'  & 
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Where  to  Go  From  Here 


There  are  many  useful  client  programs  supplied  with  the  X Window  System.  Details  of  how 
to  use  the  two  most  important  of  these  clients,  the  twm  window  manager  and  the  xterm  termi- 
nal emulator  are  provided  in  the  next  two  chapters.  Clients  to  list  and  display  fonts  are  de- 
scribed in  Chapter  5.  Chapter  6 describes  several  graphics  utilities  available  with  X.  An 
overview  and  tutorial  for  other  clients  is  provided  in  Chapter  7.  All  clients  are  described  in 
detail  in  a reference  page  format  in  Part  Three  of  this  guide. 

You  should  read  at  least  the  chapter  on  twm  before  starting  up  any  other  clients.  You  can 
then  go  on  to  read  more  about  xterm  in  Chapter  4 or  about  other  clients  in  Chapters  5 through 
7. 
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Using  the  twm  Window  Manager 


This  chapter  describes  twm,  the  standard  window  manager  distributed  with 
X.  Additional  information  on  customizing  the  operation  of\ wm  is  provided  in 
Chapter  10. 

In  This  Chapter: 


Starting  the  Window  Manager 34 

Titlebars  34 

The  Twm  Menu 35 

Displaying  Windows  as  Icons 36 

Resizing  Windows  38 

Moving  Windows  and  Icons  39 

Shuffling  the  Window  Stack:  Raise  and  Lower  40 

Raising  Windows  (bringing  in  front  of  others)  41 

Lowering  Windows  (sending  behind  others)  42 

Changing  Keyboard  Focus 43 

Removing  a Window:  Delete  and  Kill 43 

Restarting  the  Window  Manager 44 

Exiting  the  Window  Manager  44 

Button  Control  of  Window  Manager  Functions 45 

Using  twm  to  Place  Other  Clients 45 

Customizing  twm  46 

Some  of  My  Keystrokes  are  Missing  46 


Using  the  twm 
Window  Manager 


3 

Using  the  twm  Window  Manager 


The  twm  window  manager  is  primarily  a window  manipulation  tool.  It  allows  you  to: 

• Size  and  position  client  windows  on  the  screen  interactively. 

• Move  windows  around  the  screen. 

• Change  the  size  of  windows. 

• Lower  windows  (send  them  to  the  back  of  others). 

• Raise  windows  (bring  them  to  the  front  of  others). 

• Convert  windows  to  icons  and  icons  to  windows. 

• Remove  windows. 

The  twm  window  manipulation  functions  can  be  invoked  in  four  ways: 

• Using  the  titlebar. 

• Using  the  Twm  menu. 

• By  combinations  of  keyboard  keys  and  pointer  buttons. 

• Automatically,  when  a client  is  started  (to  allow  you  to  size  and  place  the  client  window 
on  the  screen). 

This  chapter  discusses  each  of  these  subjects  in  detail,  but  first  we’ll  take  a look  at  starting 
twm. 
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Starting  the  Window  Manager 


As  described  in  Chapter  2,  Getting  Started , you  start  twm  from  the  command  line  by  typing: 

% twm  & 

in  an  xterm  window.  If  xdm  (the  display  manager)  is  starting  X on  your  system,  the  twm 
window  manager  is  probably  started  automatically  when  you  log  on.  It  may  also  be  started 
automatically  from  an  jcinitrc  file.  (See  Appendix  A,  System  Management,  for  details.) 
When  twm  is  started,  you  will  see  it  add  a titlebar  to  each  window.  Titlebars  are  useful;  we’ll 
say  more  about  them  in  the  next  section. 

Note  also  that  you  can  run  xterm  or  other  X clients  without  running  a window  manager,  twm 
allows  you  to  size  and  place  client  windows  on  the  screen,  but  you  can  also  use  command 
line  options  to  do  this.  However,  there  is  no  easy  way  to  change  the  size  or  location  of  win- 
dows on  the  screen  without  a window  manager. 


Titlebars 


When  twm  starts  up,  it  places  a titlebar  on  every  window  on  the  screen.  This  titlebar  contains 
the  name  of  the  window  (“xterm,”  for  example),  two  buttons,  and  a region  that  is  highlighted 
when  the  input  focus  is  in  the  associated  window. 

The  titlebar  provides  convenient  access  to  the  most  commonly  used  window  manager  func- 
tions: iconify,  resize,  raise,  and  lower.  Iconify  allows  you  to  shrink  an  unneeded  window  so 
that  it’s  out  of  your  way.  Resize  allows  you  to  change  the  size  of  a window.  Raise  and  lower 
change  the  window’s  position  with  respect  to  other  windows  that  may  be  partially  or  com- 
pletely covering  it.  All  this  without  having  to  bring  up  a menu  or  type  modifier  keys!  (See 
Figure  3-1  for  a closer  look  at  the  titlebar.) 

From  the  titlebar,  you  can: 

• Iconify  the  window,  by  clicking  the  first  pointer  button  (usually  the  leftmost)  in  the  left- 
hand  command  button  in  the  titlebar  (it’s  marked  with  an  X). 

• Resize  the  window,  by  pressing  the  first  pointer  button  in  the  right-hand  command  button 
in  the  titlebar  (which  contains  a group  of  nested  squares).  Then,  while  holding  down  the 
first  pointer  button,  move  the  pointer  across  the  border  you  want  to  move.  Drag  the 
pointer  to  move  the  border  the  desired  amount  and  then  release  the  pointer  button. 

• Raise  the  window  to  the  top  of  the  stack,  by  clicking  the  first  pointer  button  on  the 
titlebar. 

• Lower  the  window  to  the  bottom  of  the  stack,  by  clicking  the  middle  pointer  button  on 
the  titlebar. 

• Move  the  window,  by  pressing  and  holding  down  the  left  pointer  button  on  the  titlebar, 
dragging  the  window  to  a new  location,  and  releasing  the  pointer  button. 
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Figure  3-1.  Anatomy  of  a twm  titlebar 


These  functions  can  also  be  invoked  from  a menu  and  will  be  discussed  more  thoroughly  in 
the  next  section. 


The  Twm  Menu 


twm’s  Twm  menu  gives  you  access  to  many  of  the  most  frequently  used  window  manipulation 
functions.  In  the  standard  version  of  twm  shipped  by  MIT,  you  bring  up  this  menu  by  moving 
the  pointer  to  the  root  window  and  holding  down  the  left  pointer  button.  The  Twm  menu  and 
the  menu  pointer  appear  as  shown  in  Figure  3-2. 

The  following  pages  explain  the  functions  of  the  Twm  menu.  Remember  that  all  of  the  win- 
dow manager  functions  are  customizable.  Items  can  be  added  to  or  deleted  from  this  menu, 
and  new  menus  can  be  defined  by  modifying  the  .twmrc  window  manager  startup  file,  as 
described  in  Chapter  10,  Customizing  the  twm  Window  Manager.  The  current  chapter 
describes  the  window  manager  as  it  is  shipped  with  the  standard  release  of  the  X Window 
System  from  the  MIT  X Consortium. 

To  bring  up  the  Twm  menu,  move  the  pointer  to  the  root  window  and  hold  down  the  left  but- 
ton on  the  pointer.  To  select  a menu  item,  continue  to  hold  down  the  left  button  and  move  the 
pointer  to  the  desired  menu  item.  A horizontal  band,  or  highlighting  bar , follows  the  pointer. 
When  you’ve  highlighted  the  desired  menu  item,  release  the  button.  The  selected  function 
will  be  executed. 
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Figure  3-2.  Twm  menu 


Some  of  the  functions  on  the  menus  can  be  invoked  simply  by  pressing  a combination  of 
pointer  buttons  and  keyboard  keys.  We  discuss  these  “keyboard  shortcuts”  as  appropriate 
when  discussing  each  menu  function,  and  summarize  them  in  Table  3-1  later  in  this  Chapter. 
Some  of  these  shortcuts  make  use  of  the  “Meta”  modifier  key.  See  Chapter  1 1 , Setup  Clients, 
for  a discussion  of  how  to  determine  which  key  on  your  keyboard  serves  as  the  Meta  key. 
(For  the  Sun-3  keyboard,  for  example,  Meta  is  either  of  the  keys  labeled  “Left”  or  “Right.”) 


Displaying  Windows  as  Icons 

If  you  want  to  make  more  space  available  on  your  screen,  you  can  convert  a window  into  an 
icon.  An  icon  is  a small  symbol  that  represents  the  application  window.  You  can  also  con- 
vert the  icon  back  into  a window,  as  shown  in  Figure  3-3  and  Figure  3-4. 

To  convert  a window  to  an  icon: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Iconify  with  the  menu  pointer.  The  pointer  changes  to  the  target  pointer. 

3.  Move  the  target  pointer  to  the  desired  window. 

4.  Click  the  left  button.  The  window  is  converted  to  an  icon. 
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Figure  3-3.  The  login  window  is  about  to  become  an  icon 


Figure  3-4.  The  login  window  is  about  to  be  deiconified 
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To  display  an  icon  as  its  original  window,  simply  click  the  left  button  on  the  icon,  twm  has  a 
couple  of  advanced  techniques  for  managing  icons.  One,  the  Icon  Manager , will  be  dis- 
cussed in  the  next  section.  The  other,  the  Icon  Region , is  documented  in  the  twm  man  page. 


The  Icon  Manager 

The  Show  Iconmgr  and  Hide  Iconmgr  menu  items  control  a twm  feature  called  the  Icon  Man- 
ager. The  Icon  Manager  is  a small,  menu-like  window  that  contains  one  entry  for  each  win- 
dow on  the  screen.  An  iconified  window  will  have  a small  X before  it;  a window  can  be 
iconified  and  deiconified  just  by  clicking  on  its  entry  in  the  Icon  Manager.  The  Icon  Manager 
also  highlights  the  window  with  the  current  input  focus. 

By  using  the  Icon  Manager  in  conjunction  with  the  variable  Iconif  yByUnmapping,  you 
can  keep  all  your  icons  conveniently  in  one  place,  and  avoid  searching  for  icons  that  have 
been  hidden  under  other  windows.  See  Chapter  10,  Customizing  the  twm  Window  Manager , 
for  information  on  setting  variables  in  twm. 


Resizing  Windows 

The  Resize  menu  item  resizes  an  existing  window.  See  Figure  3-5.  To  resize  a window: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Resize  with  the  menu  pointer.  The  pointer  changes  to  the  cross  pointer. 

3.  Move  the  cross  pointer  to  the  window  you  want  to  resize.  Place  it  near  the  border  you 
want  to  move.  The  opposite  border  remains  in  its  current  position. 

4.  Hold  down  any  button. 

5.  Move  the  pointer  across  the  border  you  want  to  change,  then  move  the  window’s  border 
to  obtain  the  desired  window  size.  As  you  resize  the  window,  a digital  readout  appears 
opposite  the  pointer  showing  the  window  size  in  pixels.  (For  the  xterm  client,  size  is  in 
characters  and  lines.)  Release  the  button. 

Resizing  an  xterm  window  will  not  change  the  dimensions  of  the  text  currently  in  the  win- 
dow. (If  you  make  the  window  smaller,  for  instance,  some  of  the  text  may  be  obscured.) 
However,  if  the  operating  system  supports  terminal  resizing  capabilities  (for  example,  the 
SIGWINCH  signal  in  systems  derived  from  BSD  4.3),  xterm  will  use  these  facilities  to  notify 
programs  running  in  the  window  whenever  it  is  resized.  As  you  continue  to  work,  perhaps 
starting  an  editing  session,  the  program  will  use  the  entire  window.  If  you  resize  during  an 
editing  session,  the  text  editing  program  may  not  know  about  the  new  size,  and  may  operate 
incorrectly.  Simply  quitting  out  of  the  editor  and  starting  another  session  should  solve  this 
problem. 

If  your  resized  xterm  window  does  not  seem  to  know  its  new  size,  you  may  be  working  with 
an  operating  system  that  does  not  support  terminal  resizing  capabilities.  Refer  to  the  discus- 
sion of  the  resize  client  in  Chapter  4,  The  xterm  Terminal  Emulator,  (and  to  the  resize  refer- 
ence page  in  Part  Three  of  this  guide)  for  alternative  solutions. 
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Figure  3-5.  Resizing  a window 

Moving  Windows  and  Icons 

The  Move  menu  item  moves  a window  or  an  icon  to  a new  location.  When  you  use  this  func- 
tion, an  outline,  not  the  entire  window  or  icon,  tracks  the  pointer  movement  to  the  new  loca- 
tion. See  Figure  3-6.  To  move  a window: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Move  with  the  menu  pointer.  The  pointer  changes  to  the  cross  pointer. 

3.  Move  the  cross  pointer  to  the  desired  window  or  icon.  Hold  down  any  button.  Move  the 
pointer  and  a window  outline  appears.  This  outline  tracks  the  pointer  movement. 

4.  Move  the  cross  pointer  with  the  window  outline  to  the  desired  location  on  your  screen. 

5.  Release  the  button.  The  window  will  move  to  the  new  location. 


Using  the  twm  Window  Manager 


39 


Using  the  twm 
Window  Manager 


Figure  3-6.  Moving  windows  or  icons 

You  can  also  move  a window  or  icon  simply  by  moving  the  pointer  to  the  window  or  icon 
you  want  to  move,  then  pressing  the  right  pointer  button  while  holding  down  the  Meta  key. 
The  pointer  at  first  changes  to  a small  image  of  an  icon.  You  can  now  let  go  of  the  Meta  key. 
Then,  as  you  drag  the  pointer  while  holding  down  the  button,  the  pointer  changes  to  a cross, 
while  the  window  or  icon  changes  to  outline  form.  Drag  the  outline  to  the  new  location,  and 
let  go  of  the  right  button.  The  window  will  be  redrawn  in  the  new  location. 


Shuffling  the  Window  Stack:  Raise  and  Lower 

Under  the  X Window  System,  windows  can  overlap  each  other.  When  windows  overlap,  one 
or  more  windows  may  be  fully  or  partially  hidden  behind  other  windows  (see  Figure  3-7). 
You  can  think  of  these  windows  as  being  stacked  on  top  of  each  other  much  the  way  papers 
are  stacked  on  a desk,  twm  can  control  the  stacking  order  of  the  windows  by  lowering  a par- 
ticular window  to  the  bottom  of  the  stack  or  raising  it  to  the  top. 
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Figure  3-7.  One  xterm  window  overlapping  another 

Raising  Windows  (bringing  in  front  of  others) 

The  Raise  menu  item  places  a window  at  the  top  of  a window  stack.  See  Figure  3-8.  To 
bring  a window  to  the  front: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Raise  with  the  menu  pointer.  The  pointer  changes  to  the  target  pointer. 

3.  Move  the  target  pointer  to  the  desired  window. 

4.  Click  any  button.  The  window  is  raised  to  the  top  of  the  stack. 
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Figure  3-8.  Raising  a window 

Lowering  Windows  (sending  behind  others) 
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The  Lower  menu  item  places  a window  at  the  bottom  of  a window  stack.  To  place  a window 
at  the  bottom: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Lower  with  the  menu  pointer.  The  pointer  changes  to  the  target  pointer. 

3.  Move  the  target  pointer  to  the  appropriate  window. 

4.  Click  any  button.  The  desired  window  is  placed  behind  all  windows  except  the  root  win- 
dow. 


To  raise  or  lower  a window  without  using  the  menu: 

• To  raise  a window,  move  the  pointer  so  that  the  cursor  is  within  the  titlebar  of  the  window 
you  want  to  raise,  then  click  the  left  pointer  button.  The  window  is  raised. 

• To  lower  a window,  move  the  pointer  so  that  the  cursor  is  within  the  titlebar  of  the  win- 
dow you  want  to  lower,  then  click  the  middle  pointer  button.  The  window  is  lowered. 
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Changing  Keyboard  Focus 


Normally,  keyboard  input  goes  to  whichever  window  the  pointer  is  currently  in.  The  Focus 
option  causes  keyboard  input  to  go  only  to  a selected  window  (the  focus  window)  regardless 
of  the  position  of  the  pointer. 

Focusing  can  be  useful  if  you  are  working  in  one  window  for  an  extended  period  of  time,  and 
want  to  move  the  pointer  out  of  the  way.  It  also  prevents  the  annoying  situation  in  which  you 
inadvertently  knock  the  pointer  out  of  the  window  while  typing.  (This  can  be  very  important 
for  touch  typists  who  look  infrequently  at  the  screen  while  typing!) 

To  choose  a focus  window: 

1 . Bring  up  the  Twm  menu. 

2.  Select  Focus  with  the  menu  pointer.  The  pointer  changes  to  the  target  pointer. 

3.  Move  the  target  pointer  to  the  window  you  want  to  choose  as  the  focus  window. 

4.  Click  any  button  to  choose  the  window. 

The  titlebar  of  the  focus  window  will  remain  highlighted,  no  matter  where  you  move  the 
pointer. 

In  order  to  take  the  focus  away  from  the  selected  window  (and  reactivate  “pointer  focus”), 
select  Unfocus.  The  keyboard  focus  will  once  again  follow  the  pointer  into  any  window. 


Removing  a Window:  Delete  and  Kill 

The  Delete  and  Kill  menu  items  provide  two  different  ways  of  terminating  a client  window. 
Most  windows  can  be  removed  in  ways  that  do  not  harm  relevant  processes.  Delete  is  one  of 
these  ways.  It  simply  requests  that  the  client  close  itself  down  gracefully. 

Like  other  methods  of  “killing”  a program  (such  as  the  x kill  client),  the  Kill  menu  item  can 
adversely  affect  underlying  processes.  Kill  is  intended  to  be  used  primarily  after  more  con- 
ventional methods  of  removing  a window  have  failed. 

To  remove  a window: 

1 . Bring  up  the  Twm  menu. 

2.  Select  Delete  with  the  menu  pointer.  The  pointer  changes  to  the  skull  and  crossbones 
pointer. 

3.  Move  the  pointer  into  the  window  you  want  to  terminate. 

4.  Click  any  pointer  button. 

The  window  should  go  away.  It  may,  instead,  beep  and  remain  on  your  screen.  You  have  a 
stubborn  window,  which  can  be  killed  in  the  following  way: 
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1.  Bring  up  the  Twm  menu. 

2.  Select  Kill  with  the  menu  pointer.  The  pointer  changes  to  the  skull  and  crossbones  pointer. 

3.  Move  the  pointer  into  the  window  you  want  to  terminate. 

4.  Click  any  pointer  button. 

The  window  will  go  away. 

Refer  to  the  section  on  xkill  in  Chapter  7,  Other  Clients , for  a more  complete  discussion  of 
the  hazards  of  killing  a client  and  a summary  of  alternatives. 

Restarting  the  Window  Manager 

The  Restart  menu  item  restarts  the  window  manager.  This  may  occasionally  become  neces- 
sary if  the  window  manager  functions  improperly.  To  stop  and  restart  the  window  manager: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Restart  with  the  menu  pointer. 

You  may  also  want  to  restart  the  window  manager  if  you  edit  your  .twmrc  configuration  file 
to  change  the  functionality  of  twm.  See  Chapter  10,  Customizing  the  twm  Window  Manager , 
for  more  information. 

Note  that  when  the  window  manager  is  stopped,  all  icons  revert  to  windows.  This  happens 
because  the  window  manager  is  what  allows  windows  to  be  iconified.  When  the  window 
manager  is  restarted,  you  can  iconify  the  windows  again. 

Exiting  the  Window  Manager 

The  Exit  menu  item  stops  the  window  manager.  You  may  want  to  stop  twm  in  order  to  start 
another  window  manager.  To  stop  twm: 

1.  Bring  up  the  Twm  menu. 

2.  Select  Exit  with  the  menu  pointer. 

The  window  manager  is  stopped.  All  icons  revert  to  windows. 
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Button  Control  of  Window  Manager  Functions 


Table  3-1  summarizes  the  keyboard  and  titlebar  shortcuts  for  window  management  functions. 
The  first  column  lists  the  desired  function;  the  second,  the  required  location  for  the  pointer; 
and  the  third,  the  button-key  combination.  In  this  column,  “click”  means  to  press  and  imme- 
diately release  the  specified  pointer  button;  “down”  means  to  press  and  hold  the  pointer  but- 
ton, and  “drag”  means  to  move  the  pointer  while  holding  down  the  pointer  button.  In  all 
cases,  you  can  let  go  of  the  keyboard  key  as  soon  as  you  have  pressed  the  appropriate  pointer 
button. 

Note  that  these  key  “bindings”  can  be  changed  in  your  .twmrc  file,  as  described  in  Chapter 
10.  The  combinations  described  in  the  table  work  for  the  system. twmrc  file. 

Table  3-1.  Keyboard  Shortcuts  for  Window  Manager  Functions 


Function 

Pointer  Location 

Keyboard  Shortcut 

move 

titlebar 

First  pointer  button  down  and  drag 

move 

window  or  icon 

Meta  key,  right  pointer  button  down 
and  drag 

resize 

"nested  squares"  titlebutton 

Any  pointer  button  down,  cross 
desired  border,  and  drag 

raise 

titlebar 

First  pointer  button  click 

raise 

window  or  icon 

Meta  key,  third  pointer  button  click 

lower 

titlebar 

Second  (middle)  pointer  button  click 

lower 

window  or  icon 

Meta  key,  first  pointer  button  click 

iconify 

"X"  titlebutton 

Any  pointer  button  click 

iconify 

window 

Meta  key,  second  pointer  button  click 

deiconify 

icon 

Second  pointer  button  click 

Twm  menu 

root 

First  pointer  button  down 

Customizing  twm 

The  twm  window  manager  is  a powerful  tool  that  can  perform  many  more  functions  than  are 
described  in  this  chapter.  You  can  customize  twm  using  the  .twmrc  file  in  your  home  direc- 
tory. Customizing  this  file,  you  can: 

• Define  your  own  twm  menus. 

• Bind  functions  to  keyboard  key/pointer  button  combinations. 

• Issue  command  strings  to  the  shell. 

For  details  on  customizing,  and  an  example  of  a modified  .twmrc  file,  see  Chapter  10,  Cus- 
tomizing the  twm  Manager. 
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Some  of  My  Keystrokes  are  Missing 


If  you  are  running  Release  4,  especially  if  you  are  running  on  a small  or  slow  system,  you 
may  notice  that  the  system  can’t  keep  up  with  the  movement  of  the  pointer.  You  may  move 
from  one  window  to  another  and  begin  typing,  only  to  find  that  your  first  few  characters  were 
entered  into  the  original  window,  or  dropped  into  intervening  windows. 

This  annoying  problem  is  caused  by  a subtle  interaction  between  the  operating  system,  the  X 
server,  and  the  window  manager.  It  is  unlikely  to  be  fixed  in  the  near  future,  but  twm  pro- 
vides a workaround:  setting  the  variable  NoTitleFocus  in  your  .twmrc  file  should  keep 
the  bug  from  popping  up.  See  Chapter  10  for  information  on  creating  a .twmrc  file  and  set- 
ting variables. 
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The  xterm  Terminal  Emulator 

This  chapter  describes  how  to  use  xterm,  the  terminal  emulator.  You  use  this 
client  to  create  multiple  terminal  windows,  each  of  which  can  run  any  pro- 
grams available  on  the  underlying  operating  system. 

In  This  Chapter: 

The  Release  4 xterm  Menus 50 

The  xterm  Menus  at  a Glance 50 

The  Main  Options  Menu 52 

VT  Options  Menu 55 

VT  Fonts  Menu  57 

Tek  Options  Menu 58 

Using  the  Scrollbar  59 

Copying  and  Pasting  Text  Selections  61 

Selecting  Text  to  Copy 62 

Pasting  Text  Selections 64 

Manipulating  Text  Selections 65 

Copying  and  Pasting  between  Release  2 and  3 Clients:  xcutsel 66 

Saving  Multiple  Selections:  xclipboard  (Release  4 Version)  68 

Problems  with  Large  Selections 71 

Editing  Text  Saved  in  the  xclipboard  71 

Release  3 xclipboard  72 

Terminal  Emulation  and  the  xterm  Terminal  Type  73 

Resizing  an  xterm  Window 74 

Running  a Program  in  a Temporary  xterm  Window  75 


xterm  Terminal 
Emulator 


4 
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xterm  provides  you  with  a terminal  within  a window.  Anything  you  can  do  using  a standard 
terminal,  you  can  do  in  an  xterm  window.  Once  you  have  an  xterm  window  on  your  screen, 
you  can  use  it  to  run  other  clients. 

You  can  bring  up  more  than  one  xterm  window  at  a time.  For  example,  you  might  want  to  list 
the  contents  of  a directory  in  one  window  while  you  edit  a file  in  another  window.  Although 
you  can  display  output  simultaneously  in  several  windows,  you  can  type  into  only  one  win- 
dow at  a time. 

Basic  operation  of  x term  should  be  obvious  to  anyone  familiar  with  a terminal.  You  should 
be  able  to  work  productively  immediately. 

Among  the  less  obvious  features  of  xterm  is  a dual  functionality.  By  default,  xterm  emulates 
a DEC  VT102  terminal,  a common  alphanumeric  terminal  type.  However,  xterm  can  also 
emulate  a Tektronix  4014  terminal,  which  is  used  to  display  graphics.  For  each  xterm  pro- 
cess, you  can  switch  between  these  two  types  of  terminal  windows.  You  can  display  both  a 
VT102  and  a Tektronix  window  at  the  same  time,  but  only  one  of  them  can  be  the  “active” 
window,  i.e.,  the  window  receiving  input  and  output.  Hypothetically,  you  could  be  editing  in 
the  VT102  window  while  looking  at  graphics  in  the  Tektronix  window. 

You  switch  between  the  VT102  window  and  the  Tektronix  window  using  items  from  certain 
xterm  menus.  The  xterm  client  has  four  menus  that  can  be  used  to  manipulate  the  VT102  and 
Tek  windows,  to  select  many  terminal  settings,  and  to  run  other  commands  that  affect  the 
xterm  process.  We’ll  take  a look  at  some  of  the  more  useful  items  on  each  menu  as  well  as 
some  alternatives  to  menu  items.  For  more  complete  information  about  menus,  see  the  xterm 
reference  page  in  Part  Three  of  this  guide. 

We’ll  also  discuss  two  of  xterm' s more  important  features:  a scrollbar,  which  allows  you  to 
review  text  in  the  window,  and  a “copy  and  paste”  facility. 

Finally,  we’ll  consider  problems  involved  in  resizing  an  xterm  window  and  how  to  run  a pro- 
gram in  a temporary  xterm  window. 
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The  Release  4 xterm  Menus 


The  Release  4 version  of  xterm  has  four  different  menus: 

• Main  Options  menu  (formerly  called  xterm  menu). 

• VT  Options  menu  (formerly  called  Modes  menu). 

• VT  Fonts  menu  (available  as  of  Release  4). 

• Tek  Options  menu  (formerly  called  Tektronix  menu). 

The  VT  Fonts  menu,  which  allows  you  to  dynamically  change  the  xterm  display  font,  was 
introduced  in  Release  4.  The  other  three  menus  are  updated  versions  of  menus  available  in 
Release  3.  As  is  indicated  above,  these  three  menus  have  been  renamed  in  Release  4.  Most 
of  the  items  available  on  these  menus  have  not  changed  in  functionality  since  Release  3, 
though  many  have  been  renamed  and  some  have  been  reorganized. 

For  instance,  the  R3  xterm  menu  offered  an  item  called  Redraw;  the  R4  Main  Options  menu 
offers  the  same  item,  renamed  Redraw  Window.  The  Visual  Bell  item  available  on  the  R3 
xterm  menu  in  R4  has  been  renamed  Enable  Visual  Bell  and  moved  to  the  VT  Options  menu,  a 
more  logical  location. 

A few  menu  items  are  entirely  new  as  of  Release  4.  This  chapter  describes  the  R4  xterm 
menus.  For  those  who  are  still  running  Release  3,  we’ve  tried  to  point  out  the  differences: 
the  equivalent  R3  menu  and  item  names,  what  items  have  been  moved  within  a menu  or  to 
another  menu,  and  what  items  are  only  available  in  R4. 


The  xterm  Menus  at  a Glance 

As  shown  in  Figure  4-1,  three  of  the  four  xterm  menus  arc  divided  into  sections,  separated  by 
horizontal  lines.  The  top  portion  of  each  divided  menu  contains  various  modes  that  can  be 
toggled.  (The  one  exception  is  the  Redraw  Window  item  (formerly  Redraw)  on  the  Main 
Options  menu,  which  is  a command.)  A check  mark  appears  next  to  a mode  that  is  currently 
active.  Selecting  one  of  these  modes  toggles  its  slate. 

The  items  on  the  VT  Fonts  menu  change  the  font  in  which  text  is  displayed  in  the  xterm  win- 
dow. Only  one  of  these  fonts  can  be  active  at  a time.  To  toggle  one  off,  you  must  activate 
another. 

Most  mode  entries  can  also  be  set  by  command  line  options  when  invoking  xterm,  or  by 
entries  in  a resource  startup  file  (such  as  Xdefaults  or  Xresources ) as  described  in  Chapter  9, 
Setting  Resources.  (See  the  xterm  reference  page  in  Part  Three  of  this  guide  for  a complete 
list  of  command  options  and  resource  variables.)  The  various  modes  on  the  menus  are  very 
helpful  if  you’ve  set  (or  failed  to  set)  a particular  mode  on  the  command  line  and  then  decide 
you  want  the  opposite  characteristic. 

The  sections  below  the  modes  portion  of  each  menu  contain  various  commands.  Selecting 
one  of  these  commands  performs  the  indicated  function.  Many  of  these  functions  can  only  be 
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Figure  4-1.  The  Release  4 xterm  menus 


invoked  from  the  xterm  menus.  However,  some  functions  can  be  invoked  in  other  ways: 
from  a twm  menu,  on  the  command  line,  by  a sequence  of  keystrokes  (such  as  Control-C). 
This  chapter  includes  alternatives  to  some  of  the  menu  items,  alternatives  which  in  certain 
cases  may  be  more  convenient.  Of  course,  the  xterm  menus  can  be  very  helpful  when  other 
methods  to  invoke  a function  fail. 

Menus  are  displayed  by  pressing  a combination  of  keyboard  keys  and  pointer  buttons.  (The 
exact  combination  of  keys  and  buttons  is  described  below  with  each  menu.)  When  you  dis- 
play an  x term  menu,  the  pointer  becomes  the  arrow  pointer  and  initially  appears  in  the 
menu’s  title.  Once  the  menu  appears,  you  can  release  any  keyboard  key.  The  menu  will 
remain  visible  so  long  as  you  continue  to  hold  down  the  appropriate  pointer  button. 

If  you  decide  not  to  select  a menu  item  after  the  menu  has  appeared,  move  the  pointer  off  the 
menu  and  release  the  button.  The  menu  disappears  and  no  action  is  taken. 

In  the  following  discussions  of  the  four  xterm  menus,  we’ll  consider  some  of  the  more  useful 
items  as  well  as  some  alternatives  to  menu  items.  For  more  complete  information  about  each 
menu,  see  the  xterm  reference  page  in  Part  Three  of  this  guide. 
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The  Main  Options  Menu 


The  Main  Options  menu,  shown  in  Figure  4-2,  (formerly  called  the  xterm  menu)  allows  you  to 
set  certain  modes  and  to  send  signals  (such  as  SIGHUP)  that  affect  the  xterm  process. 

To  bring  up  the  Main  Options  menu,  move  the  pointer  to  the  xterm  window  you  wish  to  effect 
changes  on,  hold  down  the  Control  key,  and  press  the  first  (usually  the  left)  pointer  button.* 
The  pointer  changes  to  the  menu  pointer,  and  the  following  menu  of  three  modes  and  eight 
commands  appears.  (You  can  release  the  Control  key  but  must  continue  to  press  the  first 
pointer  button  to  hold  the  Main  Options  menu  in  the  window.) 

Note  that  Main  Options  menu  items  apply  only  to  the  xterm  window  the  pointer  is  in  when 
you  display  the  menu.  To  effect  changes  in  another  xterm,  you  must  move  the  pointer  to  that 
window,  display  the  menu,  and  specify  the  items  you  want. 


Main  Options 

Secure  Keyboard 
Allow  SendEvents 
Log  to  File 
Redraw  Window 


Send  STOP  Signal 
Send  CONT  Signal 
Send  INT  Signal 
Send  HUP  Signal 
Send  TERM  Signal 
Send  KILL  Signal 


Quit 


Figure  4-2.  The  Main  Options  menu 


To  select  a menu  item,  move  the  menu  pointer  to  that  item  and  release  the  first  button.  After 
you  have  selected  a mode  (Secure  Keyboard,  Allow  SendEvents,  or  Log  to  File),  a check  mark 
appears  before  the  item  to  remind  you  that  it  is  active.!  The  Log  to  File  mode  on  the  Main 
Options  menu  can  also  be  set  by  a command  line  option  when  invoking  xterm.  In  addition, 
both  Log  to  File  and  Allow  SendEvents  can  be  set  by  entries  in  a resource  startup  file  like 
Xresources  (see  Chapter  9,  Setting  Resources).  The  menu  selections  enable  you  to  change 
your  mind  once  xterm  is  running.  (See  the  xterm  reference  page  in  Part  Three  of  this  guide 
for  more  information  on  these  modes.) 

*The  right  button  can  be  made  to  function  as  the  “first”  button.  This  is  especially  useful  if  you  are  left-handed.  See 
Chapter  1 1,  Setup  Clients,  for  instructions  on  how  to  customize  the  pointer  with  xmodmap. 

fThe  Allow  SendEvents  mode  is  available  as  of  Release  4.  Log  to  File  is  available  in  Release  3 as  Logging.  The  equiv- 
alent Release  3 menu  (called  xterm)  also  includes  a Visual  Bell  mode  toggle.  As  of  Release  4,  this  item  has  been 
renamed  Enable  Visual  Bell  and  moved  to  the  VT  Options  menu. 
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The  Secure  Keyboard  mode  toggle  has  been  added  to  the  menu  (in  a Release  3 patch)  to  help 
counteract  one  of  the  security  weaknesses  of  X.  This  mode  is  intended  to  be  activated  when 
you  want  to  type  a password  or  other  important  text  in  an  xterm  window.  Generally,  when 
you  press  a keyboard  key  or  move  the  pointer,  the  X server  generates  a packet  of  information 
that  is  available  for  other  clients  to  interpret.  These  packets  of  information  are  known  as 
events.  Moving  the  pointer  or  pressing  a keyboard  key  causes  input  events  to  occur. 

There  is  an  inherent  security  problem  in  the  client-server  model.  Because  events  such  as  the 
keys  you  type  in  an  xterm  window  are  made  available  via  the  server  to  other  clients,  hypo- 
thetically an  adept  system  hacker  could  access  this  information.  (Naturally,  this  is  not  an 
issue  in  every  environment.)  A fairly  serious  breach  of  security  could  easily  occur,  for 
instance,  if  someone  were  able  to  find  out  a user’s  password  or  the  root  password.  Enabling 
Secure  Keyboard  mode  causes  all  user  input  to  be  directed  only  to  the  x term  window  itself. 

Of  course,  in  many  environments,  this  is  probably  not  necessary:  if  the  nature  of  the  work  is 
in  no  way  sensitive,  if  the  system  administrator  has  taken  pains  to  secure  the  system  in  other 
ways,  etc.  If  your  environment  might  be  vulnerable,  you  can  enable  Secure  Keyboard  mode 
before  typing  passwords  and  other  important  information  and  then  disable  it  again  using  the 
menu. 

When  you  enable  Secure  Keyboard  mode,  the  foreground  and  background  colors  of  the  xterm 
window  will  be  exchanged  (as  if  you  had  enabled  the  Reverse  Video  mode  from  the  VT 
Options  menu),  as  shown  in  Figure  4-3.  When  you  disable  Secure  Keyboard  mode,  the  colors 
will  be  switched  back. 

Be  aware  that  only  one  X client  at  a time  can  secure  the  keyboard.  Thus,  if  you  have  enabled 
Secure  Keyboard  mode  in  one  xterm,  you  will  not  be  allowed  to  enable  it  in  another  xterm 
until  you  disable  it  in  the  first.  If  Secure  Keyboard  mode  is  not  available  when  you  request  it, 
the  colors  will  not  be  switched  and  a bell  will  sound. 

If  you  request  Secure  Keyboard  mode  and  are  not  refused,  but  the  colors  arc  not  exchanged, 
be  careful:  you  are  not  in  Secure  Keyboard  mode.  If  this  happens,  there’s  a good  chance  that 
someone  has  tampered  with  the  system.  If  the  application  you’re  running  displays  a prompt 
before  asking  for  a password,  it’s  a good  idea  to  enable  Secure  Keyboard  mode  before  the 
prompt  is  displayed  and  then  verify  that  the  prompt  is  displayed  in  the  proper  colors.  Before 
entering  the  password,  you  can  also  display  the  Main  Options  menu  again  and  verify  that  a 
check  mark  appears  next  to  Secure  Keyboard  mode. 

Be  aware  that  Secure  Keyboard  will  be  disabled  automatically  if  you  iconify  the  xterm  win- 
dow, or  start  twm  or  another  window  manager  that  provides  a titlebar  or  other  window  deco- 
ration. This  limitation  is  due  to  the  X protocol.  When  the  mode  is  disabled,  the  colors  will 
be  switched  back  and  the  bell  will  sound  to  wam  you. 

In  addition  to  modes  that  can  be  toggled,  the  Main  Options  menu  includes  several  commands. 
All  of  the  commands  (except  for  Redraw  Window)  send  a signal  that  is  intended  to  affect  the 
xterm  process:  suspend  it  (Send  STOP  Signal),  terminate  it  (Send  TERM  Signal),  etc.  Given 
that  your  operating  system  may  recognize  only  certain  signals,  every  menu  item  may  not  pro- 
duce the  intended  function. 

Note  that  most  of  these  commands  are  equivalent  to  common  keystroke  commands,  which 
are  generally  simpler  to  invoke.  For  example,  in  most  terminal  setups,  Control-C  can  be  used 
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Figure  4-3.  Reverse  video  is  enabled  when  the  keyboard  is  secure 

to  interrupt  a process.  This  is  generally  simpler  than  using  the  Send  INT  Signal  menu  com- 
mand (Interrupt  program  in  prior  releases),  which  performs  the  same  function. 

Similarly,  if  your  system  supports  job  control,  you  can  probably  suspend  a process  by  typing 
Control-Z  and  start  the  process  again  by  typing  Control-Y,  rather  than  using  the  Send  STOP 
Signal  and  Send  CONT  Signal  menu  commands.  (These  commands  were  called  Suspend  pro- 
gram and  Continue  program  in  Release  3.)  If  your  system  does  not  support  job  control,  nei- 
ther the  menu  commands  nor  the  keystrokes  will  work. 

Four  of  the  commands  (Send  HUP  Signal,  Send  TERM  Signal,  Send  KILL  Signal,  and  Quit*) 
send  signals  that  are  intended  to  terminate  the  ; derm  window.  Depending  on  the  signals  your 
system  recognizes,  these  commands  may  or  may  not  work  as  intended.  Be  aware  that  in  most 
cases,  you  can  probably  end  an  xterm  process  simply  by  typing  some  sequence  (such  as 
Control-D  or  exit)  in  the  window.  Of  course,  the  menu  items  may  be  very  helpful  if  the 
more  conventional  ways  of  killing  the  window  fail.  Also  be  aware  that,  in  addition  to  being 
recognized  only  by  certain  systems,  some  signals  are  more  gentle  to  systems  than  others.  See 
the  xterm  reference  page  in  Part  Three  of  this  guide  for  information  on  the  signal  sent  by 
each  of  the  menu  commands  and  the  signal{ 3C)  reference  page  in  the  UNIX  Programmer’ s 
Manual  for  more  information  on  what  each  signal  does. 


*The  first  three  of  these  commands  were  called  Hangup,  Terminate,  and  Kill  in  Release  3.  Quit  has  not  been  renamed. 
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The  Quit  command  sends  the  SIGHUP  signal  to  the  process  group  of  the  process  running 
under  xterm,  usually  the  shell.  (The  Send  HUP  Signal  command  sends  the  same  signal.)  This 
ends  up  killing  the  xterm  process,  and  the  window  disappears  from  the  screen. 

Quit  is  separated  from  the  earlier  commands  by  a horizontal  line,  so  it’s  easier  to  point  at. 
Sending  a SIGHUP  signal  with  Quit  is  also  slightly  more  gentle  to  the  system  than  sending  a 
SIGKJLL  signal  with  Send  KILL  Signal. 

The  Redraw  Window  command  redraws  the  contents  of  the  window.  As  an  alternative,  you 
can  redraw  the  entire  screen  using  the  xrefresh  client.  See  the  xrefresh  reference  page  in  Part 
Three  of  this  guide  for  more  information  about  this  client. 

If  you  are  still  using  the  uwm  window  manager,  the  Redraw  and  Refresh  Screen  selections  of 
the  WindowOps  menu  redraw  a selected  window  and  the  entire  screen,  respectively.  See 
Appendix  B,  The  uwm  Window  Manager,  for  more  about  these  uwm  menu  items. 


VT  Options  Menu 

The  VT  Options  menu  (formerly  the  Modes  menu)  provides  many  VT102  setup  functions. 
Some  of  these  mode  settings  are  analogous  to  those  available  in  a real  VT102’s  setup  mode; 
others,  such  as  scrollbar,  are  xterm- only  modes. 

The  VT  Options  menu  items  allow  you  to  reset  several  modes  at  once,  to  select  the  Tektronix 
window  to  accept  input,  and  to  hide  the  VT  window. 

The  Release  4 version  of  this  menu  is  very  similar  to  the  Release  3 version.  A majority  of  the 
mode  toggles  have  been  renamed  by  adding  the  first  word  “Enable.”  For  example,  Jump 
Scroll  has  been  renamed  Enable  Jump  Scroll,  making  it  more  apparent  when  a check  mark 
precedes  it  that  the  mode  is  active.  The  names  of  a few  of  the  other  items  have  been  changed 
slightly:  Enable  Visual  Bell  has  been  added  from  the  Main  Options  menu,  and  Show  Tek  Win- 
dow has  been  moved  from  the  mode  toggles  section  of  the  menu  below  to  the  commands 
section. 

To  bring  up  the  VT  Options  menu,  move  the  pointer  to  the  xterm  window,  hold  down  the 
Control  key,  and  then  press  and  hold  down  the  middle  pointer  button.  (You  can  release  the 
Control  key  but  must  continue  to  press  the  middle  button  to  keep  the  VT  Options  menu  in  the 
window.)  The  menu  shown  in  Figure  4-4  appears. 

Check  marks  indicate  the  active  modes.  For  example,  Jump  Scroll,  Auto  Wraparound,  and 
Scroll  to  Bottom  on  Tty  Output  are  active  in  the  VT  Options  menu  displayed  in  Figure  4-4. 
(These  are  the  only  modes  active  by  default.  In  Release  3,  Scroll  to  Bottom  on  Tty  Output  was 
not  active  by  default.*)  To  turn  off  one  of  these  modes,  move  the  menu  pointer  to  that  mode 
and  release  the  middle  button. 


*In  Release  3,  if  you  enable  the  scrollbar  for  a particular  window,  the  mode  Scroll  to  Bottom  on  Tty  Output  is  turned  on 
automatically.  This  mode  indicates  that  if  you  are  using  the  scrollbar  and  the  window  receives  output  (or  a key  is 
pressed,  if  stty  echo  is  enabled),  the  window  scrolls  forward  so  that  the  cursor  is  at  the  current  line.  (You  can  use 
the  menu  to  toggle  this  mode  off,  but  it  is  generally  desirable  to  have.) 
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VT  Options 

Enable  Scrollbar 

/ Enable  Jump  Scroll 

Enable  Reverse  Video 
/ Enable  Auto  Wraparound 

Enable  Reverse  Wraparound 

Enable  Auto  Linefeed 

Enable  Application  Cursor  Keys 
Enable  Application  Keypad 

Scroll  to  Bottom  on  Key  Press 

/ Scroll  to  Bottom  on  Tty  Output 

Allow  80/132  Column  Switching 

Enable  Curses  Emulation 

Enable  Visual  Bell 

Enable  Margin  Bell 

Show  Alternate  Screen 

Do  Soft  Reset 

Do  Full  Reset 

Show  Tek  Window 

Switch  to  Tek  Mode 

Hide  VT  Window 

Figure  4-4.  The  VT  Options  menu 

Most  of  these  modes  can  also  be  set  by  command  line  options  when  invoking  xterm,  or  by 
entries  in  a resource  startup  file  like  X resources  (see  Chapter  9,  Setting  Resources ).  The 
menu  selections  enable  you  to  change  your  mind  once  xterm  is  running. 

The  toggle  Allow  80/132  Column  Switching  warrants  a little  more  explanation.  This  mode 
allows  xterm  to  recognize  the  DECCOLM  escape  sequence,  which  switches  the  terminal 
between  80-  and  132-column  mode.  The  DECCOLM  escape  sequence  can  be  included  in  a 
program  (such  as  a spreadsheet)  to  allow  the  program  to  display  in  132-column  format.  See 
Appendix  F,  xterm  Control  Sequences , for  more  information.  This  mode  is  off  by  default. 

The  VT  Options  menu  commands  (in  the  second  and  third  partitions  of  the  menu)  perform  two 
sets  of  functions,  neither  of  which  can  be  performed  from  the  command  line  or  a resource 
definition  file.  The  commands  Soft  Reset  and  Full  Reset  reset  some  of  the  modes  on  the 
menu  to  their  initial  states.  See  the  xterm  reference  page  in  Part  Three  of  this  guide  for  more 
information. 

The  Show  Tek  Window,  Switch  to  Tek  Mode,  and  Hide  VT  Window  menu  items  allow  you  to 
manipulate  the  Tektronix  and  VT102  windows. 

The  Show  Tek  Window  command  displays  the  Tek  window  and  its  contents,  without  making  it 
the  active  window  (you  can’t  input  to  it).  Use  the  Switch  to  Tek  Mode  command  to  display  a 
Tektronix  window  and  make  it  the  active  window.  When  you  select  Switch  to  Tek  Mode,  the 
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Show  Tek  Window  command  is  enabled  automatically,  since  the  Tek  window  is  displayed. 
(Note  that  a Tektronix  window  is  not  commonly  used  for  general  purpose  terminal  emulation, 
but  for  displaying  the  output  of  graphics  or  typesetting  programs.) 

Both  of  these  commands  are  toggles.  If  Show  Tek  Window  is  active  and  you  toggle  it  off,  the 
Tek  window  becomes  hidden.  (As  we’ll  see,  you  can  also  do  this  with  the  Hide  Tek  Window 
item  on  the  Tek  Options  menu.)  If  both  Switch  to  Tek  Mode  and  Show  Tek  Window  are  active 
(remember,  enabling  the  former  automatically  enables  the  latter),  toggling  either  one  of  them 
off  switches  the  xterm  back  to  VT  mode.  (This  can  also  be  done  from  the  Tek  Options  menu 
with  the  Switch  to  VT  Mode  item.) 

The  Hide  VT  Window  command  hides  the  VT102  window,  but  does  not  destroy  it  or  its  con- 
tents. It  can  be  restored  (and  made  the  active  window)  by  choosing  Select  VT  Mode  from  the 
Tek  Options  menu. 


VT  Fonts  Menu 

The  VT  Fonts  menu  is  a welcome  Release  4 innovation.  It  allows  you  to  change  the  display 
font  of  an  xterm  window  while  the  window  is  running.  To  bring  up  the  VT  Fonts  menu,  move 
the  pointer  inside  the  xterm  window.  Press  the  Control  key  on  the  keyboard;  while  holding 
down  the  Control  key,  press  the  third  (right)  pointer  button.  The  VT  Fonts  menu  is  shown  in 
Figure  4-5. 


VT  Fonts 

/ Default 

Tiny 

Small 

Medium 

Large 

Escape  Sequence 
Selection 

Figure  4-5.  VT  Fonts  menu 


If  you  have  not  toggled  any  items  on  this  menu,  a check  mark  will  appear  before  the  Default 
mode  setting.  The  Default  is  the  font  that  was  specified  when  the  xterm  window  was  run. 
This  font  could  have  been  specified  on  the  xterm  command  line  or  in  a resource  file  like 
Xresources.  Whatever  the  case,  this  font  remains  the  Default  for  the  duration  of  the  current 
xterm  process. 


The  items  Default,  Tiny,  Small,  Medium,  and  Large  can  be  toggled  to  set  the  font  displayed  in 
the  xterm  window.  The  font  can  be  changed  any  number  of  times,  to  accommodate  a variety 
of  uses.  You  might  choose  to  use  a large  font  for  editing  a file  (chances  are  you’ve  chosen  a 
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large  enough  default  font,  though).  You  could  then  change  to  a smaller  font  while  a process 
is  running  and  you  don’t  need  to  be  reading  or  typing  in  that  xlerm.  Changing  the  font  also 
changes  the  size  of  the  window. 

There  are  also  default  settings  for  the  Tiny,  Small,  Medium,  and  Large  fonts.  They  are  all  con- 
stant width  fonts  from  the  directory  lusrllib/Xl  1 Ifonlslmisc  and  are  listed  in  Table  4-1. 

Table  4-1.  VT  Fonts  Menu  Defaults 


Menu  Item 

Default  Font 

Tiny 

nil2 

Small 

6x10 

Medium 

8x13 

Large 

9x15 

Bring  up  the  VT  Fonts  menu,  and  toggle  some  of  these  fonts  to  see  what  they  look  like.  The 
default  Tiny  font,  nil2,  is  actually  too  small  to  be  legible.  It  is  not  intended  to  be  read.  If  you 
select  this  font,  your  xlerm  window  becomes  tiny,  almost  the  size  of  some  application  icons. 
Though  you  cannot  read  the  actual  text  in  a window  this  size,  the  window  is  still  active  and 
you  can  observe  if  additional  output,  albeit  minuscule,  is  displayed.  An  xterm  window  dis- 
playing text  in  such  a small  font  can  serve,  in  effect,  as  an  active  icon. 

Be  aware  that  you  can  specify  your  own  Tiny,  Small,  Medium,  and  Large  fonts  using  entries  in 
a resource  startup  file  like  Xresources.  The  corresponding  resource  names  are  fontl, 
font  2,  font  3,  and  font  4.  See  Chapter  5,  Font  Specification,  for  more  information  about 
available  fonts.  See  Chapter  9,  Setting  Resources,  for  instructions  on  how  to  set  resource 
variables. 

In  addition  to  the  menu  selections  we’ve  discussed,  the  VT  Fonts  menu  offers  two  other  pos- 
sible selections:  Escape  Sequence  and  Selection.  When  you  first  run  an  xterm  window, 
these  selections  appear  on  the  VT  Fonts  menu,  but  they  are  not  functional.  (They  will  appear 
in  a lighter  typeface  than  the  other  selections,  indicating  that  they  are  not  available.)  In  order 
to  enable  these  selections  for  use,  you  must  perform  certain  actions,  which  are  outlined  in 
Chapter  5,  Font  Specification,  after  we  discuss  font  specification  in  greater  detail. 


Tek  Options  Menu 

The  Tek  Options  menu  (formerly  Tektronix)  controls  certain  modes  and  functions  of  the  Tek- 
tronix window.  The  menu  can  only  be  displayed  from  within  the  Tektronix  window.  As  pre- 
viously described,  you  can  display  the  Tek  window  and  make  it  the  active  window  by  using 
the  Switch  to  Tek  Mode  command  on  the  VT  Options  menu. 

To  display  the  Tek  Options  menu,  move  the  pointer  inside  the  Tektronix  window.  Press  the 
Control  key  on  the  keyboard;  while  holding  down  the  Control  key,  press  the  middle  pointer 
button.  The  Tek  Options  menu  appears.  With  this  menu,  you  set  the  size  of  the  text  in  the 
Tektronix  window  and  select  some  commands. 
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Tek  Options 

/ Large  Characters 
#2  Size  Characters 
#3  Size  Characters 
Small  Characters 

PAGE 

RESET 

COPY 

Show  VT  Window 
Switch  to  VT  Mode 
Hide  Tek  Window 

'rK'Vv-  ' ' S'  ' '-V  ' : ■ - ■ ■ : • 

Figure  4-6.  The  Tek  Options  menu 


Note  that  these  modes  (above  the  first  line)  can  only  be  set  from  the  Tek  Options  menu.  All 
of  these  modes  set  the  point  size  of  the  text  displaying  in  the  Tektronix  window.  (Only  one 
of  these  four  modes  can  be  enabled  at  any  time.) 

The  most  important  command  on  the  Tek  Options  menu,  shown  in  Figure  4-6,  is  Switch  to  VT 
Mode  (formerly  Select  VT  Mode).  If  the  Tek  window  has  been  made  the  active  window 
(using  the  Switch  to  Tek  Mode  command  from  the  VT  Options  menu),  you  can  choose  Switch 
to  VT  Mode  to  make  the  VT  window  the  active  window  again.  (If  both  windows  are  showing, 
you  can  also  toggle  Switch  to  Tek  Mode  on  the  VT  Options  menu  to  deactivate  it;  that  is, 
switch  from  Tek  mode  and  back  to  VT  mode.)  Switch  to  VT  Mode  is  also  a toggle;  if  you 
deactivate  it,  xterm  will  switch  back  to  Tek  mode. 

Selecting  Show  VT  Window  (formerly  VT  Window  Showing),  displays  the  VT  window  if  it  has 
been  hidden  (using  the  Hide  VT  Window  command  from  the  VT  Options  menu),  or  hides  it  if  it 
is  being  displayed.  (Again,  the  command  is  a toggle.)  Remember  that  you  cannot  input  to 
the  VT  window  until  you  make  it  the  active  window,  using  Switch  to  VT  Mode. 


Using  the  Scrollbar 

When  using  xterm,  you  are  not  limited  to  viewing  the  24  lines  displayed  in  the  window.  By 
default,  xterm  actually  remembers  the  last  64  lines  that  have  appeared  in  the  window.  If  the 
window  has  a scrollbar,  you  can  scroll  up  and  down  through  the  saved  text.  If  the  window 
was  not  created  with  a scrollbar,  you  can  add  one  using  the  Enable  Scrollbar  item  on  the  VT 
Options  menu. 

To  create  a single  x term  window  with  a scrollbar,  use  the  -sb  command  line  option: 

% xterm  -sb  & 
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To  display  all  xterm  windows  with  a scrollbar  by  default,  set  scrollBar  in  your 
•X resources  file,  as  described  in  Chapter  9,  Setting  Resources.  This  is  illustrated  below: 

XTerm*scrollBar : true 

Figure  4-7  shows  an  xterm  window  with  a scrollbar. 


The  thumb  (the  highlighted  area  within  the  scrollbar)  moves  within  the  scroll  region.  The 
thumb  displays  the  position  and  amount  of  text  currently  showing  in  the  window  relative  to 
the  amount  saved.  When  an  xterm  window  with  a scrollbar  is  first  created,  the  thumb  fills  the 
entire  scrollbar.  As  more  text  is  saved,  the  size  of  the  thumb  decreases.  The  number  of  lines 
saved  is  64  by  default,  but  an  alternative  can  be  specified  with  either  the  -si  command  line 
option  or  the  saveLines  value  in  an  Xresources  file. 

When  the  pointer  is  positioned  in  the  scrollbar,  the  cursor  changes  to  a two-headed  arrow. 
Clicking  the  first  (usually  the  left)  pointer  button  in  the  scrollbar  causes  the  window  to  scroll 
toward  the  end  of  information  in  the  window. 

Clicking  the  third  (usually  the  right)  pointer  button  in  the  scrollbar  causes  the  window  to 
scroll  toward  the  beginning  of  information  in  the  window. 

Clicking  the  second  (usually  the  middle)  pointer  button  moves  the  display  to  a position  in  the 
saved  text  that  corresponds  to  the  pointer’s  position  in  the  scroll  region.  For  example,  if  you 
move  the  pointer  to  the  very  top  of  the  scroll  region  and  click  the  second  (middle)  button,  the 
display  is  positioned  very  near  the  beginning  of  the  saved  area. 
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If  you  hold  down  the  second  button,  you  can  drag  the  thumb  up  and  down.  Text  moves  as 
you  move  the  thumb.  If  you  drag  up,  the  window  scrolls  back,  toward  the  beginning  of  infor- 
mation in  the  window.  If  you  drag  down,  the  window  scrolls  forward,  toward  the  end  of 
information  in  the  window.  When  you  release  the  button,  the  window  displays  the  text  at  that 
location.  This  makes  it  easy  to  get  to  the  top  of  the  data  by  pressing  the  second  button,  drag- 
ging it  off  the  top  of  the  scrollbar,  and  releasing  it. 


Copying  and  Pasting  Text  Selections 

Once  your  xterm  window  is  created,  you  can  select  text  to  copy  and  paste  within  the  same  or 
other  xterm  windows  using  the  pointer.  You  don’t  need  to  be  in  a text  editor  to  use  copy  and 
paste.  You  can  also  copy  or  paste  text  to  and  from  the  command  line. 

Text  copied  into  memory  using  the  pointer  is  saved  in  a global  cut  buffer  and  also  becomes 
what  is  known  as  the  PRIMARY  text  “selection.”  Both  the  contents  of  the  cut  buffer  and  the 
contents  of  the  PRIMARY  text  selection  are  globally  available  to  all  clients.  When  you  paste 
text  into  an  x term  window,  by  default  the  contents  of  the  PRIMARY  selection  are  pasted.  If 
there  is  no  text  in  the  PRIMARY  selection,  the  contents  of  the  cut  buffer  (called 
CUT_BUFFERO),  are  pasted.  (Thus,  in  most  cases,  these  will  be  the  same.) 

Copying  and  pasting  is  one  way  in  which  clients  exchange  information,  in  this  case,  text. 
Prior  to  Release  3,  many  clients  exchanged  information  solely  by  means  of  cut  buffers.  Cut 
buffers  are  only  useful  for  transferring  information  between  clients  that  interpret  data  in  the 
same  format.  Thus,  cut  buffers  could  be  used  to  transfer  ASCII  text  between  xterm  windows. 
In  accordance  with  the  newer  interclient  communication  conventions  developed  since 
Release  2,  most  Release  3 and  4 clients,  notably  xterm , primarily  exchange  information  via 
selections.  The  advantage  of  the  selection  mechanism  is  that  it  allows  data  from  one  client  to 
be  converted  to  a different  format  to  be  used  by  another  client.  Cut  buffers  do  not  perform 
this  type  of  translation. 

As  we’ve  said,  if  you  are  copying  text  between  xterm  windows,  the  contents  of 
CUT_BUFFERO  and  the  PRIMARY  selection  should  be  the  same.  However,  as  we’ll  see  later, 
while  some  applications  (notably  the  current  version  of  xterm)  copy  to  both  the  cut  buffer 
and  the  selection,  other  applications  (generally  prior  to  Release  3)  only  copy  to  the  cut  buffer. 
If  you  are  using  both  types  of  applications  together  and  trying  to  transfer  text  between  them, 
differences  between  the  contents  of  the  cut  buffer  and  the  PRIMARY  selection  may  make 
copying  and  pasting  problematic.  If  you  are  only  copying  text  between  xterm  windows 
(Release  3 or  later),  problems  of  this  type  will  never  arise. 

For  our  purposes,  we  are  mainly  concerned  with  ASCII  text  selections  from  xterm  windows. 
First,  we’ll  show  you  how  to  copy  and  paste  text  between  xterm  windows.  Then  we’ll  dis- 
cuss some  of  the  implications  of  using  selections  versus  cut  buffers,  and  describe  two  clients, 
xcutsel  and  xclipboard,  which  allow  you  to  manipulate  text  saved  in  memory.  The  xcutsel 
client  addresses  problems  that  arise  when  you’re  copying  text  between  an  application  that 
uses  selections  and  one  that  uses  cut  buffers.  The  xclipboard  allows  you  to  store  multiple 
text  selections. 
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Selecting  Text  to  Copy 


To  select  text,  move  the  pointer  to  the  beginning  of  the  text  you  want  to  select.  Hold  down 
the  first  button  while  moving  the  pointer  to  the  end  of  the  desired  text,  then  release  the  but- 
ton. The  text  is  highlighted,  copied  into  the  global  cut  buffer  (called  CUT_BUFFERO)  and 
also  made  the  PRIMARY  selection. 

Note  that  with  the  current  implementation  of  the  copy  and  paste  feature,  tabs  are  saved  as 
spaces. 

You  can  select  a single  word  or  line  simply  by  clicking.  To  select  a single  word,  place  the 
pointer  on  the  word  and  double-click  the  first  button.*  To  select  a single  line,  place  the 
pointer  on  the  line  and  triple-click  the  first  button. 

If  you  hold  the  button  down  after  double-  or  triple-clicking  (rather  than  releasing  it)  and 
move  the  pointer,  you  will  select  additional  text  by  words  or  lines  at  a time. 

The  following  table  describes  the  button  combinations  and  the  resulting  selection.  Begin  by 
placing  the  pointer  on  your  desired  selection. 

Table  4-2.  Button  Combinations  to  Select  Text  for  Copying 


To  select 

Do  this 

Word 

Double-click  the  first  button. 

Line 

Triple-click  the  first  button. 

Passage 

Hold  down  the  first  button,  move  the  pointer, 
release  the  button. 

Each  selection  replaces  the  previous  contents  of  CUT_BUFFERO  and  the  previous  PRIMARY 
text  selection.  You  can  make  only  one  selection  at  a time. 

Once  you  have  made  a selection  with  the  first  button,  you  can  extend  that  selection  with  the 
third  button.  The  following  example  shows  how  this  works: 

1.  Bring  up  vi  (or  any  other  text  editor  with  which  you  are  familiar)  in  an  xterm  window, 
and  type  in  this  sample  sentence: 

The  X Window  System  is  a network-based  graphics  window  system  that 
was  developed  at  MIT  in  1984. 


*To  be  more  precise,  double  clicking  selects  all  characters  of  the  same  class  (e.g.,  alphanumeric  characters).  By  de- 
fault, punctuation  characters  and  whitespace  are  in  a different  class  from  letters  or  digits — hence,  the  observed  be- 
havior. However,  character  classes  can  be  changed.  For  example,  if  you  wanted  to  double-click  to  select  e-mail  ad- 
dresses, you’d  want  to  include  the  punctuation  characters  !,  %,  @,  and  . in  the  same  class  as  letters  and  digits.  How- 
ever, redefining  the  character  classes  is  not  something  you’d  do  every  day.  See  the  xterm  reference  page  in  Part 
Three  for  details. 
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2.  Place  the  pointer  on  the  word  graphics  in  the  sample  sentence  and  select  it  with  two 
clicks  of  the  first  button. 

3.  Then  press  and  hold  the  third  pointer  button.  Move  the  pointer  away  from  the  word 
graphics , to  the  left  or  right.  A new  selection  now  extends  from  the  last  selection  (graph- 
ics) to  the  pointer’s  location  and  looks  something  like  the  following: 

The  X Window  System  is  a network-based  graphics  window  system  that 
Was  developed  at  MIT  in  1934- 

or: 

The  X Window  System  is  a network-based  graphics  window  system  that 
was  developed  at  MIT  in  1984 . 

Remember  that  your  extension  always  begins  from  your  last  selection.  By  moving  the 
pointer  up  or  down,  right  or  left  of  the  last  selection,  you  can  use  this  technique  to  select  part 
of  one  line  or  add  or  subtract  several  lines  of  text. 


V 


Figure  4-8.  Highlighted  text  saved  as  the  PRIMARY  selection 

To  clear  the  highlighting,  move  the  pointer  off  the  selection  and  click  anywhere  else  in  the 
window  with  the  first  button.  Note,  however,  that  the  text  still  remains  in  memory  until  you 
make  another  selection. 
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Pasting  Text  Selections 


The  second  (middle)  button  inserts  the  text  from  the  PRIMARY  selection  (or  CUT_BUFFERO, 
if  the  selection  is  empty)  as  if  it  were  keyboard  input.  You  can  move  data  from  one  xterm 
window  to  another  by  selecting  the  data  in  one  window  with  the  first  button,  moving  the 
pointer  to  another  window,  and  clicking  the  second  button. 

You  can  paste  text  either  into  an  open  file  or  at  a command  line  prompt.  To  paste  text  into  an 
open  file,  as  illustrated  in  Figure  4-9,  click  the  second  button  within  the  window  containing 
the  file.  The  text  from  the  memory  area  will  be  inserted  where  the  text  editor  cursor  is.  (Of 
course,  the  file  must  be  in  a mode  where  it  is  expecting  text  input,  such  as  the  insert  mode  of 
an  editor.)  You  can  paste  the  same  text  as  often  as  you  like.  The  contents  of  the  PRIMARY 
selection  remain  until  you  make  another  selection. 


Figure  4-9.  Pasting  text  into  an  open  file 


To  paste  text  at  a command  line  prompt,  you  must  first  close  any  open  file  within  the  window. 
Then  click  the  second  button  anywhere  within  the  window  to  place  the  text  on  the  command 
line  at  the  end  of  text  in  the  window  (note  that  the  window  will  scroll  to  the  bottom  on  input). 

You  can  make  multiple  insertions  by  repeatedly  clicking  the  second  button. 

The  latest  text  selected  replaces  the  previous  text  selected. 
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You  can  also  paste  over  existing  text  with  the  vi  change  text  commands  (such  as  cw,  for 
change  word).  For  example,  you  can  paste  over  five  words  by  specifying  the  vi  command 
5cw,  and  then  pasting  text  by  clicking  the  second  pointer  button.  Note  that  you  can  paste 
over  existing  text  in  any  editor  that  has  an  overwrite  mode. 


Manipulating  Text  Selections 

Prior  to  Release  3,  text  copied  into  memory  using  the  pointer  was  saved  in  the  global  cut 
buffer,  in  effect,  “owned”  by  the  server,  and  available  to  all  clients.  Cut  buffers  are  only  use- 
ful for  copying  and  pasting  information  that  does  not  need  to  be  translated  to  another  format, 
such  as  ASCII  text  between  two  xterm  windows. 

Since  Release  3,  text  copied  into  memory  from  an  xterm  window  is  saved  in  the  cut  buffer 
and  as  the  PRIMARY  selection.  The  PRIMARY  selection  takes  precedence  over  the  contents 
of  the  cut  buffer.  When  pasting  text  between  xterm  windows,  if  the  selection  contains  text,  it 
is  pasted.  If  not,  the  contents  of  the  cut  buffer  are  pasted.  Selections  can  be  used  to  transfer 
data  that  must  be  translated  to  a form  the  receiving  client  can  interpret. 

A selection  is  globally  available,  but  it  is  not  owned  by  the  server.  A selection  is  owned  by  a 
client — initially  by  the  client  from  which  you  copy  it.  Then  when  the  text  selection  is  pasted 
to  another  window,  that  window  becomes  the  owner  of  the  selection. 

Because  of  the  rules  of  precedence  governing  cut  buffers  and  selections,  and  the  nature  of 
selections  (particularly  the  issue  of  ownership),  certain  problems  can  arise  in  transferring 
data: 

1.  If  one  client  communicates  with  cut  buffers  and  one  with  selections,  copying  and  pasting 
between  them  is  inherently  problematic.  By  default,  the  selection  takes  precedence. 
How  do  you  paste  the  contents  of  the  cut  buffer  instead? 

2.  By  default,  you  can  save  only  one  selection  at  a time. 

3.  For  a selection  to  be  transferred  to  a client,  the  selection  must  be  owned  by  a client.  If 
the  client  that  owns  the  selection  no  longer  exists,  the  transfer  cannot  be  made. 

The  xcutsel  and  xclipboard  clients  address  the  first  two  of  these  problems,  respectively. 

Most  users  will  probably  not  encounter  the  third  problem.  You  are  probably  doing  all  your 
copying  and  pasting  between  xterm  windows.  If  you’ve  made  a selection  from  an  xterm  win- 
dow and  the  window  is  killed,  the  selection  contents  are  lost.  However,  the  cut  buffer  con- 
tents remain  intact  and  are  pasted  instead.  (Since  all  xterm  windows  interpret  ASCII  text,  the 
translation  capabilities  of  the  selection  mechanism  are  not  needed.) 

Problems  involving  the  loss  of  selections  are  more  likely  to  happen  if  you  arc  transferring 
information  between  clients  that  require  information  to  be  in  different  formats.  If  you  are 
having  such  problems,  you  can  customize  the  clients  involved  to  copy  information  to  what  is 
known  as  the  CLIPBOARD  selection. 

The  CLIPBOARD  selection  is  intended  to  avert  problems  of  selection  ownership  by  providing 
centralized  ownership.  Once  the  CLIPBOARD  owns  a selection,  the  selection  can  be 
transferred  (and  translated),  even  if  the  client  that  previously  owned  the  selection  goes  away. 
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You  can  customize  a client  to  send  data  to  the  CLIPBOARD  selection  by  using  event  transla- 
tions, which  are  discussed  in  Chapter  9,  Setting  Resources.  See  the  client  reference  pages  for 
information  on  the  appropriate  translations.  For  more  information  on  selections  and  transla- 
tions, see  Volume  One,  XI ib  Programming  Manual. 


Copying  and  Pasting  between  Release  2 and  3 Clients:  xcutsel 

The  xcutsel  client  is  intended  to  bridge  a gap  that  exists  between  the  ways  older  and  newer 
clients  allow  you  to  copy  text.  If  all  the  clients  you  are  using  are  from  Release  3 or  later,  you 
will  probably  have  no  use  for  xcutsel  and  should  skip  ahead  to  the  next  section.* 

Since  Release  3,  when  you  select  text  from  an  x term  window  with  the  pointer,  the  text  is 
copied  into  the  global  cut  buffer  and  made  the  PRIMARY  selection.  (Thus,  generally,  the 
contents  of  the  cut  buffer  and  the  PRIMARY  selection  are  the  same.)  By  default,  the  PRI- 
MARY selection  is  what  gets  pasted  into  a window.  If  there  is  no  PRIMARY  selection,  the 
contents  of  the  cut  buffer  arc  pasted. 

Prior  to  Release  3,  clients  did  not  use  selections.  Text  was  copied  into  the  cut  buffer  only 
(and  was  not  equated  with  a PRIMARY  selection).  Problems  can  arise  if  you  are  running  cli- 
ents that  use  cut  buffers  only  (many  Release  2 clients  and  uwm,  any  release)  with  clients  that 
primarily  use  selections  (Release  3 and  later)  and  arc  trying  to  paste  text  between  them. 

For  instance,  say  you  copy  text  in  a Release  3 xterm  window  using  the  pointer.  The  text  is 
copied  into  the  cut  buffer  and  also  becomes  the  PRIMARY  selection.  If  you  paste  in  any  win- 
dow, the  PRIMARY  selection  is  what  you  get.  Then,  say  you  copy  text  in  a R2  xterm  window. 
The  text  is  stored  in  the  cut  buffer,  replacing  the  text  in  the  cut  buffer  from  the  R3  window, 
but  it  does  not  replace  the  PRIMARY  selection.  You  can  paste  the  text  from  the  R2  window  in 
another  R2  window  because  the  window  only  understands  cut  buffers,  but  you  can’t  paste  it 
in  an  R3  window.  If  you  try  to,  by  default  you  get  the  PRIMARY  selection  (from  the  other  R3 
window). 

xcutsel  enables  you  to  switch  the  text  in  the  cut  buffer  and  the  PRIMARY  election  so  that  you 
can  cut  and  paste  between  clients  that  use  cut  buffers  and  clients  that  use  selections. 

To  open  an  xcutsel  window,  type: 

% xcutsel  £ 

and  then  place  the  window  on  your  screen.  Figure  4-10  shows  an  xcutsel  window. 

The  window  contains  three  command  buttons  whose  functions  are  described  below: 

quit  Exits  the  xcutsel  program. 

copy  PRIMARY  to  0 Copies  the  contents  of  the  PRIMARY  selection  to  CUT_BUFFER0. 

copy  0 to  PRIMARY  Copies  the  contents  of  CUTJBUFFERO  to  the  primary  selection. 


*If  you  are  using  uwm,  you  may  have  use  {or  xcutsel.  Regardless  of  the  release,  uwm  uses  only  cut  buffers.  See 
Appendix  B,  The  uwm  Window  Manager,  of  this  guide  for  details. 
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Now  let’s  go  back  to  the  problem  we  set  up  earlier  in  this  section.  If  you  copy  text  from  an 
R2  window  and  want  to  paste  in  an  R3  window,  you  merely  click  on  the  copy  0 to  PRIMARY 
button.  The  contents  of  the  cut  buffer  (from  the  R2  client)  replace  the  previous  PRIMARY 
selection  (from  the  R3  client).  When  you  paste,  you  get  the  text  you  want  (from  the  R2 
window). 

Now  say  you  have  the  same  situation,  but  the  opposite  problem.  You  made  a selection  from 
an  R3  window,  which  filled  the  cut  buffer  and  the  PRIMARY  selection.  Then  you  copied  text 
from  an  R2  window,  which  merely  filled  the  buffer.  (The  contents  of  the  buffer  and  the  PRI- 
MARY selection  are  different.)  But  now  say  you  want  to  paste  the  text  from  the  PRIMARY 
selection  (from  the  R3  window)  in  an  R2  window.  If  you  paste  text  in  an  R2  window,  you  get 
the  contents  of  the  cut  buffer  (the  text  from  the  other  R2  window). 

To  solve  this  problem,  just  click  on  the  copy  PRIMARY  to  0 button  in  the  xcutsel  window. 
The  contents  of  the  PRIMARY  selection  (from  the  R3  window)  replace  the  contents  of  the  cut 
buffer  (from  the  R2  window).  When  you  paste  in  an  R2  window,  you  get  still  get  the  con- 
tents of  the  cut  buffer,  but  it  is  now  the  text  you  want. 

This  business  of  selections  versus  cut  buffers  can  be  pretty  confusing.  If  you  have  problems 
pasting  the  text  you  want,  experiment  a little  with  xcutsel. 
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Saving  Multiple  Selections:  xclipboard  (Release  4 Version) 


The  xclipboard  client  provides  a window  in  which  you  can  paste  multiple  text  selections  and 
from  which  you  can  copy  text  selections  to  other  windows.  Similar  to  the  clipboard  feature 
of  the  Macintosh  operating  system,  the  xclipboard  is  basically  a storehouse  for  text  you  may 
want  to  paste  into  other  windows,  perhaps  multiple  times.  The  xclipboard  window  is  shown 
in  Figure  4-11. 

This  section  and  the  next  two  sections  describe  various  features  of  the  Release  4 version  of 
xclipboard.  If  you  are  using  the  Release  3 version,  which  has  more  limited  functionality,  also 
read  the  section  “Release  3 xclipboard”  later  in  this  chapter. 


(Quit)  (Delete^  (New^  ^ (:  . 

A 

\ 

• 'i  -..V  I 

y 

Figure  4-1 1.  The  xclipboard  window 


To  open  an  xclipboard , type: 

% xclipboard  & 

and  then  place  the  window  interactively  with  the  pointer. 

You  can  paste  text  into  the  xclipboard  window  using  the  pointer  in  the  manner  described 
above  and  then  copy  and  paste  it  elsewhere,  but  this  is  not  its  intended  usage.  To  use  the 
x clipboard  most  effectively,  you  must  do  some  customization  involving  a resource  file,  such 
as  Xresources.  The  necessary  steps  are  described  in  detail  in  Chapter  9,  Setting  Resources. 
For  now,  suffice  it  to  say  that  you  want  to  set  up  the  xclipboard  so  that  you  can  select  text  to 
be  made  the  CLIPBOARD  selection  and  have  that  text  automatically  pasted  in  the  xclip- 
board window.  This  is  illustrated  in  Figure  4-12. 

Since  the  xclipboard  client  is  intended  to  be  coordinated  with  the  CLIPBOARD  selection, 
the  X server  allows  you  to  run  only  one  xclipboard  at  a time. 

In  order  to  illustrate  how  the  clipboard  works,  let’s  presume  it  has  been  set  up  according  to 
the  guidelines  in  Chapter  9.  According  to  those  guidelines,  you  make  text  the  CLIPBOARD 
selection  by  selecting  it  with  the  first  pointer  button  (as  usual)  and  then,  while  continuing  to 
hold  the  first  button,  clicking  the  third  button.  (You  could  specify  another  button  combina- 
tion or  a button  and  key  combination,  but  we’ve  found  this  one  works  pretty  well.  For  more 
information  about  these  specifications,  see  Chapter  9,  Setting  Resources .)  The  first  pointer 
action  makes  the  text  the  PRIMARY  selection  (and  it  is  available  to  be  pasted  in  another 
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window  using  the  pointer);  the  second  pointer  action  additionally  makes  the  text  the  CLIP- 
BOARD selection  (and  it  is  automatically  sent  to  the  xclipboard  window). 

These  guidelines  still  allow  you  to  select  text  with  the  first  pointer  button  alone,  and  that  text 
will  be  made  the  PRIMARY  selection;  however,  the  text  will  not  automatically  be  sent  to  the 
xclipboard.  This  enables  you  to  make  many  selections,  but  to  direct  to  the  xclipboard  only 
those  you  consider  important  (perhaps  those  you  might  want  to  paste  several  times). 


Figure  4-12.  Selected  text  appears  automatically  in  the  xclipboard  window 


In  order  to  allow  you  to  store  multiple  text  selections,  the  seemingly  tiny  xclipboard  actually 
provides  multiple  screens,  each  of  which  can  be  thought  of  as  a separate  buffer.  (However,  as 
we’ll  see,  a single  text  selection  can  span  more  than  one  screen.)  Each  time  you  use  the 
pointer  to  make  text  the  CLIPBOARD  selection,  the  xclipboard  advances  to  a new  screen  in 
which  it  displays  and  stores  the  text. 

Once  you  have  saved  multiple  selections,  the  client’s  Next  and  Previous  command  buttons 
allow  you  to  move  forward  and  backward  among  these  screens  of  text.  The  functionality  of 
the  client’s  command  buttons  is  summarized  in  Table  4-3.  They  are  all  selected  by  clicking 
with  the  first  pointer  button. 

Table  4-3.  Command  Buttons  and  Functions 


Button 

Function 

Quit 

Causes  the  application  to  exit. 

Delete 

Deletes  the  current  x clipboard  buffer;  the  current  screenful  of 
text  is  cleared  from  the  window,  and  the  next  screenful  (or  previ- 
ous, if  there  is  no  next)  is  displayed. 

New 

Opens  a new  buffer  into  which  you  can  insert  text;  the  window  is 
cleared. 
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Table  4-3.  Command  Buttons  and  Functions  (continued) 


Button 

Function 

Next  and  Previous 

Once  you  have  sent  multiple  selections  to  the  xclipboard.  Next 
and  Previous  allow  you  to  move  from  one  to  another  (display 
them  sequentially).  Before  two  or  more  CLIPBOARD  selections 
are  made,  these  buttons  are  not  available  for  use  (their  labels  will 
appear  in  a lighter  typeface  to  indicate  this). 

The  command  buttons  you  will  probably  use  most  frequently  are  Delete,  Next,  and  Previous. 

When  you  select  text  using  the  first  and  third  pointer  buttons,  the  text  will  automatically  be 
displayed  in  the  xclipboard  window  and  will  in  effect  be  the  first  screenful  of  text  (or  first 
buffer)  saved  in  the  xclipboard.  Subsequent  CLIPBOARD  selections  will  be  displayed  and 
saved  in  subsequent  screens. 

You  select  text  from  the  xclipboard  and  paste  it  where  you  want  it  just  as  you  would  any  text. 
Just  display  the  text  you  want  in  the  xclipboard  window,  using  Next  or  Previous  as  necessary. 
Then  select  the  text  using  the  first  pointer  button  and  paste  it  using  the  second  pointer  button. 

You  can  remove  a screenful  of  text  from  the  xclipboard  by  displaying  that  screenful  and  then 
clicking  on  the  Delete  command  button.  When  you  delete  a screenful  of  text  using  this  com- 
mand button,  the  next  screenful  (if  any)  will  be  displayed  in  the  window.  If  there  is  no  next 
screenful,  the  previous  screenful  will  be  displayed. 

Certain  features  (and  limitations)  of  the  x clipboard  become  apparent  only  when  you  make  a 
very  large  CLIPBOARD  selection.  Say  you  select  a full  xterm  window  of  text  with  the  first 
and  third  pointer  buttons,  as  described  above.  The  text  extends  both  horizontally  and  verti- 
cally beyond  the  bounds  of  a single  xclipboard  screen.  (As  we  suggested  earlier,  a CLIP- 
BOARD selection  can  actually  span  more  than  one  xclipboard  screen.  Pressing  Delete  will 
remove  all  screenfuls  comprising  the  selection.)  When  you  make  a selection  that  extends 
beyond  the  bounds  of  the  xclipboard  screen  (either  horizontally,  vertically,  or  both), 
scrollbars  will  be  activated  in  the  window  to  allow  you  to  view  the  entire  selection. 

If  the  text  extends  both  horizontally  and  vertically  beyond  the  bounds  of  the  x clipboard 
screen,  as  it  does  in  Figure  4-13,  the  window  will  display  both  horizontal  and  vertical 
scrollbars.  If  the  text  extends  beyond  the  screen  in  only  one  of  these  two  ways,  the  window 
will  display  either  a horizontal  or  vertical  scrollbar,  as  needed.*  These  scrollbars  are  selec- 
tion-specific: they  are  only  displayed  so  long  as  the  current  selection  cannot  be  viewed  in  its 
entirety  without  them.  If  you  move  to  a previous  or  subsequent  selection  that  can  be  viewed 
without  scrollbars,  the  scrollbars  will  be  deactivated. 


♦An  application  created  using  the  X Toolkit,  which  provides  horiz-ontal  and  vertical  scrollbars,  is  described  as  a 
viewport.  See  Chapter  7,  Other  Clients , for  more  information  about  viewports  and  other  X Toolkit  features. 
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Figure  4-13.  xclipboard  with  scrollbars  to  view  large  text  selection 

Problems  with  Large  Selections 

If  you  experiment  making  large  selections  with  xclipboard , you  may  discover  what  seems  to 
be  a bug  in  the  program.  Though  in  most  circumstances,  making  a new  selection  causes  the 
screen  to  advance  and  display  the  new  text,  this  does  not  happen  reliably  after  a selection 
vertically  spanning  more  than  one  screenful.  In  these  cases,  the  new  selection  is  saved  in  the 
xclipboard;  however,  the  xclipboard  window  does  not  automatically  advance  to  show  you  the 
new  current  selection.  Instead,  the  previous  long  selection  is  still  displayed.  This  is  a bit  of 
xclipboard  sleight-of-hand.  The  new  selection  has  been  successfully  made,  but  the  appear- 
ance of  the  window  belies  this  fact.  (The  Next  button  will  probably  add  to  your  confusion;  it 
will  not  be  available  for  selection,  suggesting  that  the  text  in  the  window  is  the  last  selection 
saved.  This  is  not  the  case.) 

In  order  to  get  around  this  and  display  the  actual  current  selection,  press  the  Previous  button. 
The  same  long  selection  (which  is,  in  actuality,  the  Previous  selection)  will  again  be 
displayed.  Then  the  Next  button  will  be  enabled,  and  you  can  click  on  it  to  display  the  actual 
current  selection. 

Editing  Text  Saved  in  the  xclipboard 

You  can  edit  text  you  send  to  the  xclipboard  using  the  same  commands  recognized  by  xedit. 
These  commands  are  described  in  the  section  “Text  Editing  Widget”  of  Chapter  7,  Other 
Clients.  A small  caret  cursor  will  be  visible  in  each  screenful  of  text.  You  can  move  this  cur- 
sor by  clicking  the  pointer  where  you’d  like  it  to  appear.  Then  you  can  backspace  to  delete 
letters  or  type  to  insert  them,  or  use  any  of  the  text  editing  commands  described  in  Chapter  7. 
When  you  edit  a screenful  of  text,  the  xclipboard  continues  to  store  the  edited  version,  until 
you  delete  it  or  exit  the  program. 

Be  aware  that,  without  performing  customization,  you  can  still  use  xclipboard  on  a very 
simple  level.  You  can  paste  text  into  and  copy  text  from  the  xclipboard  window  just  as  you 
would  any  other,  using  the  pointer  movements  described  earlier  in  this  chapter.  You  can  also 
type  in  the  xclipboard  window,  and  then  copy  and  paste  what  you’ve  typed.  Just  move  the 
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pointer  into  the  window  and  try  typing.  However,  keep  in  mind  that  this  is  not  the  intended 
use  of  the  xclipboard. 

If  you  do  choose  to  use  the  clipboard  in  a limited  way,  it  can  still  be  a helpful  editing  tool. 
For  example,  say  you  wanted  to  create  a paragraph  composed  of  a few  lines  of  text  from  each 
of  two  files.  You  could  copy  the  text  from  each  file  using  the  pointer  and  paste  it  into  the 
xclipboard  window.  (Each  time  you  paste  text  into  the  xclipboard  window,  the  text  is 
appended  to  whatever  text  has  already  been  pasted  there.)  Again  using  the  pointer,  you  could 
copy  the  newly  formed  paragraph  from  the  xclipboard  window  and  paste  it  into  a file  in 
another  window. 

Release  3 xclipboard 

xclipboard  was  first  shipped  as  a part  of  the  standard  version  of  X in  Release  3.  If  you  are 
using  the  Release  3 xclipboard,  shown  in  Figure  4-14,  you’ll  find  that  it’s  functionality  is 
considerably  more  limited  than  the  Release  4 version. 


Quit 

Previous 

: : ; 

A 

Figure  4-14.  The  Release  3 xclipboard  window 


The  Release  3 xclipboard  can  also  be  customized  to  receive  the  CLIPBOARD  selection  auto- 
matically. However,  this  version  of  the  xclipboard  merely  inserts  each  selection  on  the 
line(s)  following  the  previous  one.  The  screen  of  the  xclipboard  will  scroll  forward  as  you 
add  more  text,  but  at  line  intervals,  not  at  full  screen  intervals  as  the  Release  4 client  does. 
Thus,  while  the  Release  4 x clipboard  allows  you  to  save  multiple  selections  that  are  recog- 
nized as  such  by  commands  like  Delete,  the  Release  3 xclipboard  only  allows  you  to  save 
what  is,  in  effect,  a single,  running  selection.  This  limitation  alone  makes  the  Release  3 
xclipboard  far  less  useful  than  the  Release  4 xclipboard. 

But  the  Release  3 xclipboard  has  other  serious  limitations.  It  features  only  one  functioning 
command  button,  quit.  The  erase  button  in  the  window  is  not  functional,  and  unfortunately, 
no  other  key  or  combination  of  keys  seems  to  clear  the  text  from  the  xclipboard. 

Unlike  the  Release  4 version,  the  Release  3 xclipboard  does  not  recognize  all  of  the  text  edit- 
ing commands  recognized  by  xedit.  You  can  use  all  of  the  commands  that  move  the  cursor, 
but  none  of  the  commands  that  delete  text.  Your  only  option  to  remove  text  is  to  select  the 


72 


X Window  System  User’s  Guide 


quit  button,  which  closes  the  window  without  saving  its  contents,  and  open  a new  x clipboard 
window. 

You  also  cannot  change  or  add  to  any  text  once  it  is  placed  in  the  window.  You  can  type  text 
in  the  window,  but  not  within  any  pre-existing  selection.  If  you  type  text,  the  cursor  will 
automatically  advance  to  the  line  below  the  last  selection,  and  the  new  text  will  be  displayed 
there.  If  the  last  text  in  the  window  is  text  you  typed  in,  the  cursor  will  advance  to  the  end  of 
that  line  and  append  the  new  typed  text.  (Note  that  since  the  cursor  advances  automatically 
and  you  cannot  edit  any  text,  the  xedit  commands  to  move  the  cursor  are  virtually  useless.) 

Once  you  type  text  in,  it  is  treated  just  like  any  other  selection — it  cannot  be  deleted  or 
edited  in  any  way.  Likewise,  if  you  physically  paste  text  in  the  window  using  the  pointer 
(rather  than  sending  it  automatically  as  the  CLIPBOARD  selection),  it  will  appear  after  exist- 
ing text  and  cannot  be  edited  or  deleted. 

Despite  these  limitations,  you  can  still  use  the  Release  3 x clipboard  on  a very  simple  level  as 
a text  editing  tool.  Whether  you  customize  it  to  receive  CLIPBOARD  selections  automati- 
cally or  not,  the  x clipboard  can  still  be  used  as  a storehouse  for  text.  You  can  paste  text  into 
and  copy  text  from  the  xclipboard.  You  could  use  it  to  gather  text  from  several  areas,  per- 
haps forming  a new  paragraph  to  be  pasted  into  one  or  more  files.  If  you’re  a good  typist 
(since  you  cannot  correct  your  errors),  you  could  also  enter  text  in  the  window  and  then  copy 
and  paste  what  you’ve  typed. 


Terminal  Emulation  and  the  xterm  Terminal  Type 

Anyone  who  has  used  a variety  of  terminals  knows  that  they  don’t  all  work  the  same  way.  As 
a terminal  emulator,  an  xterm  window  must  be  assigned  a terminal  type,  which  tells  the  sys- 
tem how  the  window  should  operate,  that  is,  what  type  of  terminal  it  should  emulate.  When 
xterm  is  assigned  an  invalid  terminal  type,  the  window  does  not  display  properly  at  all  times, 
particularly  when  using  a text  editor,  such  as  vi.  If  one  of  your  login  files  {.login,  . profile , 
.eshre,  etc.)  currently  specifies  a default  terminal  type,  you  will  need  to  replace  this  with  a 
type  valid  for  x term.  (If  none  of  your  login  files  specifies  a terminal  type,  x term  automati- 
cally searches  the  file  of  TERMCAP  entries  for  the  first  valid  entry.) 

xterm  can  emulate  a variety  of  terminal  types,  which  are  listed  on  the  client  reference  page  in 
Part  Three  of  this  guide.  An  xterm  window  emulates  a terminal  most  successfully  when  it 
has  been  assigned  the  terminal  type  xterm.  For  the  xterm  terminal  type  to  be  recognized  on 
your  system,  the  system  administrator  will  have  had  to  add  it  to  the  file  containing  valid 
TERMCAP  entries.  (The  xterm  TERMCAP  entry  is  supplied  with  the  standard  release  of  X.) 
If  this  has  not  been  done,  the  system  will  not  recognize  the  xterm  terminal  type.  In  these 
cases,  try  the  vtlOO  terminal  type,  which  also  generally  works  well,  or  use  one  of  the  other 
types  listed  on  the  client  reference  page. 

See  Appendix  A,  System  Management,  and  the  xterm  reference  page  in  Part  Three  of  this 
guide  for  information  about  customizing  the  termcap  file. 
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Resizing  an  xterm  Window 


xterm  sets  the  TERMCAP  environment  variable  for  the  dimensions  of  the  window  you  create. 
Clients  (including  xterm ) use  this  TERMCAP  information  to  determine  the  physical  dimen- 
sions of  input  and  output  to  the  window. 

If  you  resize  an  xterm  window,  programs  running  within  the  window  must  be  notified  so  they 
can  adjust  the  dimensions  of  input  and  output  to  the  window.  If  the  underlying  operating  sys- 
tem supports  terminal  resizing  capabilities  (for  example,  the  SIGWINCH  signal  in  systems 
derived  from  BSD  4.3),  xterm  will  use  these  facilities  to  notify  programs  running  in  the 
window  whenever  it  is  resized.  However,  if  your  operating  system  does  not  support  terminal 
resizing  capabilities,  you  may  need  to  request  explicitly  that  TERMCAP  be  updated  to  reflect 
the  resized  window. 

The  resize  client  sends  a special  escape  sequence  to  the  x term  window  and  xterm  sends  back 
the  current  size  of  the  window.  The  results  of  resize  can  be  redirected  to  a file  that  can  then 
be  sourced  to  update  TERMCAP.  To  update  TERMCAP  to  match  a window’s  changed  dimen- 
sions, enter: 

% resize  > filename 

and  then  execute  the  resulting  shell  command  file: 

% source  filename  C shell  syntax 


or: 


$ . filename  Bourne  shell  syntax 

TERMCAP  will  be  updated  and  the  dimensions  of  the  text  within  the  window  will  be  adjusted 
accordingly. 

If  your  version  of  UNIX  includes  the  C shell,  you  can  also  define  the  following  alias  for 

resize : 


alias  rs  'set  noglob;  eval  'resize';  unset  noglob' 

Then  use  rs  to  update  the  TERMCAP  entry  to  reflect  a window’s  new  dimensions. 

Note  that  even  if  your  operating  system  supports  terminal  resizing  capabilities,  xterm  may 
have  trouble  notifying  programs  running  in  the  window  that  the  window  has  been  resized. 
On  some  older  systems  (based  on  BSD  4.2  or  earlier),  certain  programs,  notably  the  vi  editor, 
cannot  interpret  this  information.  If  you  resize  a window  during  a vi  editing  session,  vi  will 
not  know  the  new  size  of  the  window.  If  you  quit  out  of  the  editing  session  and  start  another 
one,  the  editor  should  know  the  new  window  size  and  operate  properly.  On  newer  systems 
(e.g.,  BSD  4.3  and  later),  these  problems  should  not  occur. 
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Running  a Program  in  a Temporary  xterm  Window 


Normally,  when  you  start  up  an  xterm  window,  it  automatically  runs  another  instance  of  the 
UNIX  Bourne  or  C shell  (depending  on  which  is  set  in  your  Xresources  file  or  the  SHELL 
environment  variable).  If  you  want  to  create  an  xterm  window  that  runs  some  other  program, 
and  goes  away  when  that  program  terminates,  you  can  do  so  with  the  xterm  -e  option: 

% xterm  -e  command  [argument s] 

For  example,  if  you  wanted  to  look  at  the  file  temp  in  a window  that  would  disappear  when 
you  quit  out  of  the  file,  you  could  use  the  UNIX  more  program  as  follows: 

% xterm  -e  more  temp 

If  you  are  using  other  options  to  xterm  on  the  command  line,  the  -e  option  must  appear  last. 
This  is  because  everything  after  the  -e  option  is  read  as  a command. 
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Font  Specification 

This  chapter  describes  what  you  need  to  know  in  order  to  select  display  fonts 
for  the  various  client  applications.  After  acquainting  you  with  some  of  the 
basic  characteristics  of  a font,  this  chapter  describes  the  rather  complex  font 
naming  conventions  and  how  to  simplify  font  specification.  This  chapter  also 
describes  how  to  use  the  xlsfonts,  xfd,  and  xfontsel  clients  to  list,  display, 
and  select  available  screen  fonts. 
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Many  clients  allow  you  to  specify  the  font  used  to  display  text  in  the  window,  in  menus  and 
labels,  or  in  any  other  text  fields.  For  example,  you  can  choose  the  font  used  for  the  text  in 
twm  menus  or  in  xterm  windows. 

Unfortunately,  for  the  most  part,  there  are  no  simple  “font  menus”  like  there  are  on  systems 
such  as  the  Macintosh.*  Instead,  X has  a fairly  complex  font  naming  system  (which,  like 
most  things  about  X,  is  designed  for  maximum  flexibility  rather  than  for  simplicity  or  ease  of 
use).  Of  course,  there  will  no  doubt  soon  be  many  applications  such  as  word  processors  and 
publishing  packages  that  provide  a simple  interface  for  selecting  fonts.  However,  for  the 
clients  in  the  X distribution,  you  are  generally  limited  to  selecting  fonts  via  command  line 
options  or  resource  specifications. 

This  wouldn’t  be  so  bad  if  a typical  font  name  wasn’t  mind-bending  at  first  glance.  Imagine 
typing  this  command  line  to  create  an  xterm  window  whose  text  is  to  be  displayed  in  14-point 
Courier  bold: 

% xterm  -fn  -adobe -courier-bold-r-normal — 14-140-75-75-m-90-±so8859-l 

Fortunately,  you  can  use  asterisks  as  wildcards  to  simplify  this  name  to  a somewhat  more  rea- 
sonable one: 

% xterm  -fn  ' *courier-bold-r*140* ' 

and  you  can  define  even  simpler  aliases,  so  that  you  could  end  up  typing  a command  line  like 
this: 

% xterm  -fn  courierB14 

In  this  chapter,  we’re  going  to  try  to  make  sense  out  of  the  sometimes  bewildering  jungle  of 
information  about  fonts  under  X.  First,  we’ll  explain  the  font  naming  convention  in  detail. 
Along  the  way,  we’ll  acquaint  you  with  the  appearance  of  some  of  the  basic  font  families 
(groups  of  related  fonts),  and  the  various  permutations  (such  as  weight,  slant,  and  point  size) 
within  each  family. 


♦An  exception  is  the  VT  fonts  menu  in  the  R4  xterm.  But  even  then,  you  need  to  know  a lot  about  font  naming  to 
change  the  fonts  on  the  menu. 
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Then,  we’ll  talk  about  how  to  use  font  name  wildcards  to  simplify  font  specification.  We’ll 
also  talk  about  the  font  search  path  (the  directories  where  the  font  files  are  stored),  and  how 
to  define  aliases  for  font  names. 

Finally,  we’ll  talk  about  some  of  the  utilities  X provides  for  dealing  with  fonts: 

• xlsfonts , which  lists  the  names  of  the  fonts  available  on  your  server,  as  well  as  any  aliases. 

• xfd  (font  displayer),  which  allows  you  to  display  the  character  set  for  any  individual  font 
you  specify  on  the  command  line. 

• xfontsel  (font  selector),  which  allows  you  to  preview  fonts  and  select  the  name  of  the  one 
you  want.  (This  name  can  then  be  pasted  onto  a command  line,  into  a resource  file,  etc.) 


Font  Naming  Conventions 

In  Release  2 and  earlier,  fonts  were  simply  identified  by  the  name  of  the  file  in  which  they 
were  stored,  minus  the  .snf  (“server  natural  format”)  extension.  For  example,  the  file 
8xl3.snf  contained  a font  named  8x13. 

However,  starting  with  Release  3,  a new  logical  font  naming  convention  was  adopted.  As 
we’ll  see  in  a moment,  these  logical  font  names  allow  for  complete  specification  of  all  of  the 
characteristics  of  each  font.  Unfortunately,  this  completeness  makes  them  somewhat  difficult 
to  work  with,  at  least  until  you  learn  what  all  the  parts  of  the  names  mean,  and  get  a handle 
on  which  parts  you  need  to  remember,  and  which  you  can  safely  ignore.  (By  the  end  of  this 
chapter,  you  should  have  that  knowledge.) 

The  xlsfonts  client  can  be  used  to  display  the  names  of  all  the  fonts  available  on  your  server. 
When  you  run  xlsfonts , you’ll  get  an  intimidating  list  of  names  similar  to  the  name  in  Figure 
5-1. 

Upon  close  examination,  this  rather  verbose  name  contains  a great  deal  of  useful  informa- 
tion: the  font’s  developer,  or  foundry  (Adobe),  the  font  family  (Courier),  weight  (bold),  slant 
(oblique),  set  width  (normal),  size  of  the  font  in  pixels  (10),  size  of  the  font  in  tenths  of  a 
point  (100  tenths  of  a point,  thus  10  points),  horizontal  resolution  (75-dpi),  vertical  resolution 
(75-dpi),  spacing  (m,  for  monospace),  average  width  (60 — measured  in  tenths  of  a pixel,  thus 
6 pixels),  and  character  set  (iso8859-l). 

As  mentioned  earlier,  font  name  wildcarding  can  eliminate  a lot  of  the  unnecessary  detail.  If 
you  are  already  familiar  with  font  characteristics,  skip  ahead  to  the  section  “Font  Name 
Wildcarding”  later  in  this  Chapter  for  some  tips  and  tricks.  If  you  need  a refresher  on  fonts, 
read  on,  as  we  illustrate  and  explain  each  of  the  elements  that  make  up  the  font  name. 
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vertical  resolution  in  dpi 


foundry 


points  (in  tenths 

weight  set  width  of  a point) 


average  width  (in 
tenths  of  a pixel) 


-adobe-courier-bold-o-normal-- 10-1 00-7 5-7 5-m-60-iso8 859-1 


font  family  slant 


pixels 


spacing  character  set 


horizontal  resolution  in  dpi 


Figure  5-1.  Font  name,  Releases  3 and  4 

Font  Families 


It  has  been  several  years  since  the  advent  of  desktop  publishing,  and  by  now,  it  is  unlikely 
that  anyone  in  the  computer  industry  is  unaware  that  text  can  be  displayed  on  the  screen  and 
printed  on  the  page  using  different  fonts. 

However,  the  term  font  is  used  somewhat  ambiguously.  Does  it  refer  to  a family  of  typefaces 
(such  as  Times®  Roman  or  Helvetica®),  which  comes  in  different  sizes,  weights,  and  orien- 
tations? Or  should  each  distinct  set  of  character  glyphs  be  considered  a separate  font? 

X takes  the  latter  approach.  When  the  documentation  says  that  Release  3 includes  1 57  fonts, 
and  Release  4 more  than  400,  this  sounds  either  intimidating  or  impressive,  depending  on 
your  mood.  But,  in  fact,  the  R3  X distribution  includes  only  six  font  families  (Courier,  Hel- 
vetica, New  Century  Schoolbook®,  Symbol,  and  Times),  plus  several  miscellaneous  fonts 
that  are  found  only  in  individual  sizes  and  orientations.1''  R4  includes  two  more  font  families, 
Lucida®  and  the  Clean  family  of  fixed  width  fonts,  plus  many  more  special  purpose  fonts. 

When  you  think  about  it  this  way,  you  can  quickly  reduce  the  clutter.  Figure  5-2  shows  the 
major  families  of  commercial  fonts  that  are  available  under  X.  To  illustrate  the  fonts,  we’ve 
used  the  simple  expedient  of  printing  each  font  name  in  the  font  itself.  Font  names  are  trun- 
cated to  fit  on  the  page.t  (For  those  of  you  who  don’t  read  the  Greek  alphabet,  the  fourth  line 
down  reads  “-adobe-symbol-medium-r-normal--18  ...”  This  font  is  used  for  mathematical 
equations  and  so  forth,  rather  than  for  normal  display  purposes.) 

*By  contrast,  the  Macintosh  supports  dozens  of  font  families,  and  commercial  typesetters  support  hundreds,  and  in 
some  cases,  even  thousands  of  families.  Many  of  these  fonts  will  doubdess  be  made  commercially  available  for  X. 
fTo  generate  the  figures  in  this  section  and  in  Appendix  E,  Release  3 and  4 Standard  Fonts,  we  wrote  a short  pro- 
gram called  xshowfonts,  which  displays  a series  of  fonts  in  a scrollable  window.  In  each  case,  we  used  wildcards 
(discussed  later  in  this  chapter)  to  select  the  fonts  we  wanted,  and  then  did  screendumps  of  the  resulting  images. 
Note  that  the  fonts  look  better  on  the  screen  than  they  do  in  the  illustration,  since  the  scaling  factor  used  to  make  the 
screen  dumps  exacerbates  the  “jaggies”  endemic  to  bitmap  fonts. 

Source  code  for  xshowfonts  is  listed  in  Appendix  E,  along  with  the  name  of  every  font,  printed  in  the  font  itself.  Ap- 
pendix E also  includes  complete  character-set  dumps  of  some  of  the  more  unusual  fonts. 
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-adobe-cour ier-medium-r-normal — 18-180-75-75-1 

-adobe-helvetica-medium-r-normal — 18-180-75-75-p-9E 
-adobe-new  century  schoolbook-medium-r-normal — 18-  ] 
-a6ope-OYjj,po^-^eoiujx-p-vopjxccA— 18- 180-75-75-ti- 107-a6 
-adobe-times -medium -r -normal — 18-180-75-75-p-94-iso88 
-b&h-lucida-medium-r-normal-sans-l  8-1 80-75-7 
-bSdi-lucidabright-medium-i^normal — 18-180-75-75- 
-b&h-lucidatypewri ter-medium-r-normal-sans-18 
-bitstream-charter-medium-r-normal--19-180-75-75-p-106-isoJ 


Figure  5-2.  The  major  commercial  font  families  available  in  the  standard  X distribution 

You’ll  notice  that  with  the  exception  of  Courier  and  Lucidatypewriter,  all  of  the  fonts  in  the 
figure  are  proportionally-spaced . That  is,  each  character  has  a separate  width.  This  makes 
them  look  good  on  a printed  page,  but  makes  them  less  appropriate  for  screen  display  in  ter- 
minal windows  (especially  for  program  editing),  since  text  will  not  line  up  properly  unless  all 
characters  are  the  same  width. 

You  will  most  likely  use  these  proportional  fonts  for  labels  or  menu  items,  rather  than  for 
running  text.  (Word  processing  or  publishing  programs  will,  of  course,  use  them  to  represent 
proportional  type  destined  for  the  printed  page.) 

Courier  and  Lucidatyperwriter  are  monospaced  fonts.  Every  character  has  the  same  width. 
Monospaced  fonts  can  be  used  effectively  for  the  text  font  in  xterm  windows.  There  are  also 
some  special  monospaced  fonts  originally  designed  for  computer  displays.  You  can  think  of 
these  as  character  cell  fonts.  They  too  are  monospaced,  but  the  spacing  relates  to  the  size  of 
a cell  that  contains  each  character,  rather  than  (necessarily)  to  the  character  itself.  Some  of 
these  fonts  were  originally  available  in  Release  2,  and  even  in  R3  they  don’t  have  the  same 
complex  names  as  the  proportional  fonts.  Instead,  they  have  simple  names  expressing  then- 
size  in  pixels.  For  example,  in  the  font  named  8x13,  each  character  occupies  a box  8 pixels 
wide  by  13  pixels  high. 

In  R4,  they  were  renamed  to  use  the  logical  font  naming  conventions,  with  a foundry  name  of 
“misc”,  and  a font-family  of  “fixed.”  There  are  also  one  or  two  larger  fixed  fonts  donated  by 
Sony  for  use  with  their  extra-high  resolution  monitor,  with  a foundry  name  of  “sony.”  Figure 
5-3  shows  the  character  cell  fonts,  using  their  R3  names,  which  still  exist  as  aliases  in  R4. 
(Not  all  of  these  fonts  were  available  in  R3.) 
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two  aliases  for 
the  same  font 


5x8 

6x10 

6x12 

6x13 

6xl3bold 

6x8 

7x13 

7xl3bold 

7x14 

8x13 

8xl3bold 

8x16 

9x15 

9xl5bold 

10x20 

12x24 

fixed 


Figure  5-3.  Miscellaneous  fonts  forxterm  text 

Table  5-1  shows  the  correspondence  between  these  aliases  and  full  font  names.  Note  that  the 
6x13  font  also  has  an  alias  called  “fixed”  defined  for  it.  The  “fixed”  alias  is  used  as  the 
default  font  for  xterm  windows.  (Twelve-point  Helvetica  bold  roman  has  the  alias  “variable” 
and  is  used  by  default  for  labels  such  as  those  in  the  titlebar  twm  puts  on  windows.) 

Table  5-1.  Fixed  Font  Aliases  and  Font  Names 


Alias 


Filename 


fixed 

5x8 

6x9 

6x10 

6x12 

6x13 

6xl3bold 

7x13 

7xl3bold 

7x14 

8x13 

8xl3bold 

8x16 


-misc-fixed-medium-r-semicondcnsed- 13-1 20-75-75-c-60-iso8859- 1 
-misc-fixed-medium-r-normal-8-80-75-75-c-50-iso8859-l 
-misc-fixed-medium-r-normal-9-90-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-normal-10-100-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-semicondensed-12-1 10-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-semicondensed- 13-1 20-75-75-c-60-iso8859- 1 
-misc-fixed-bold-r-semicondcnsed-13-120-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-normal-13-120-75-75-c-70-iso8859-l 
-misc-fixed-bold-r-normal- 13-1 20-75-75-c-70-iso8859- 1 
-misc-fixed-medium-r-normal- 14- 1 30-75-75-c-70-iso8859- 1 
-misc-fixed-medium-r-normal-13-120-75-75-c-80-iso8859-l 
-misc-fixed-bold-r-normal- 1 3- 1 20-75-75-c-80-iso8859- 1 
-sony-fixed-medium-r-normal—  1 6- 1 20-100- 1 00-c-80-iso8859- 1 
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Table  5-1.  Fixed  Font  Aliases  and  Font  Names  (continued) 


Alias 

Filename 

9x15 

9xl5bold 

10x20 

12x24 

-misc-fixed-medium-r-normal-15-140-75-75-c-90-iso8859-l 
-misc-fixed-bold-r-normal- 15-1 40-75-75-c-90-iso8859- 1 
-misc-fixed-medium-r-normal-20-200-75-75-c-100-iso8859-l 
-sony-fixed-medium-r-normal-24-170-100-100-c-120-iso8859-l 

R4  also  includes  the  Clean  family  of  fixed-width  fonts  from  Schumaker,  and  DEC’S  terminal 
fonts,  both  of  which  are  illustrated  in  Appendix  E,  Release  3 and  4 Standard  Fonts. 

There  are  also  many  other  special  purpose  fonts,  such  as  the  Greek  Symbol  font  that  we 
already  saw,  the  cursor  font,  the  OPEN  LOOK™  cursor  and  glyph  fonts,  and  Kana  and  Kanji 
Japanese  fonts.  (The  Kana  and  Kanji  fonts  can  only  be  displayed  with  special  hardware.) 
See  Appendix  E for  comprehensive  lists  of  the  these  fonts,  as  well  as  pictures  of  the  character 
set  in  some  representative  fonts. 


Stroke  Weight  and  Slant 

The  characters  in  a given  font  family  can  be  given  a radically  different  appearance  by  chang- 
ing the  stroke  weight  or  the  slant,  or  both. 

The  most  common  weights  are  medium  and  bold.  The  most  common  slants  are  roman 
(upright),  italic,  or  oblique.  (Both  italic  and  oblique  are  slanted;  however,  italic  versions  of  a 
font  generally  have  had  the  character  shape  changed  to  make  a more  pleasing  effect  when 
slanted,  while  oblique  fonts  are  simply  a slanted  version  of  the  upright  font.  In  general,  serif 
fonts  (those  with  little  decorations  on  the  ends  and  comers  of  the  characters)  are  slanted  via 
italics,  while  sans-serif  fonts  are  made  oblique.) 

Figure  5-4  compares  the  medium  and  bold  weights,  and  the  roman  and  italic  or  oblique  slants 
in  the  Charter®  and  Helvetica  font  families. 

Release  4 also  includes  one  font  that  has  an  in-between  weight  called  demibold.  Weight 
names  are  somewhat  arbitrary,  since  a demibold  weight  in  one  family  may  be  almost  as  dark 
as  a bold  weight  in  another. 

The  font  naming  convention  also  defines  two  counter-clockwise  slants,  called  reverse  italic 
(ri)  and  reverse  oblique  (ro),  as  well  as  a catch-all  called  other  (ot). 


Font  Sizes 

Font  sizes  are  often  given  in  a traditional  printer’s  measure  known  as  a point.  A point  is 
approximately  one  seventy-second  of  an  inch. 

Most  of  the  font  families  are  provided  in  the  six  point  sizes  shown  in  Figure  5-5. 


84 


X Window  System  User’s  Guide 


adobe-heivetica-medium-o-normaf — 18-  180-75-75-p-98- 
-adobe-helvetica-medium-r-normal — 18-180-75-75-p-98- 
- adobe -hefvetica  -bold -o -norma!- -18-180-75-75-p-104- 
-adobe-helvetica-bold-r-normal — 18-180-75-75-p-103 

-bitstream-charter-medium-i-n.or7nal--l  9-180-75-75-p-l  03-Lso885 

-bitstream-charter-medium-r-normal--19-180-75-75-p-106-iso8< 

-bitstream-chartei*-hold-i-normal—l  9-180-75-  75-p-l  1 ' 
-bitstream-charter-bold-r-normal-19-180-75-75-p-ll‘ 


Figure  5-4.  The  same  fonts  in  different  weights  and  slants 


8 point  -bit<tr<.»ni-ch«rttr-ni<dium-r-n*fm*l~8-80-75-75-p-45-i<o8859.l 
1 0 point  -bit*tream-charter-medium-r-normal--l  0-1 00-75-75-p'56-i*o8859-l 
12  point  -bitstream-charter-medium-r-normal-12-120-75-75-p-67-iso8859-l 
1 4 point  -bitstream-charter-medium-r-normal—15-1 40-75-75-p-84-iso8859-l 

is  point  -bitstream-charter-medium-r-normal--19-180-75-75-p-106 

24  point  -bitstream-charter- medium-r- no rmal-25-2^ 


Figure  5-5.  The  same  font  in  six  different  point  sizes 

However,  the  size  story  doesn’t  end  there.  Note  that  some  servers  (such  as  Sun’s  combined 
XI  1/NeWS™  server)  support  scalable  outline  fonts,  which  are  device-independent,  and  thus 
true  to  size  regardless  of  the  output  device.  But  the  standard  X fonts  are  simply  bitmaps. 
Because  of  the  different  resolution  of  computer  monitors,  a font  with  a given  nominal  point 
size  might  actually  appear  larger  or  smaller  on  the  screen. 

Most  monitors  on  the  market  today  have  a resolution  between  75  dots  per  inch  and  100  dots 
per  inch  (dpi).  Accordingly,  there  are  both  75-dpi  and  100-dpi  versions  of  a few  of  the  fonts 
in  R3,  and  of  most  of  them  in  R4.  These  separate  versions  of  each  font  are  stored  in  different 
directories.  By  setting  the  font  search  path  so  that  the  appropriate  directory  comes  first,  you 
can  arrange  to  get  the  correct  versions  without  having  to  specify  them  in  the  font  name.*  But 
how  do  you  tell  which  kind  of  monitor  you  have? 

If  you  have  the  manufacturer’s  specs  on  your  monitor,  they  might  give  you  this  figure.  But 
more  likely,  they’ll  give  you  the  overall  resolution  in  rows  and  columns.  After  measuring  the 
physical  screen,  you  can  do  some  rough  calculations  to  arrive  at  the  equivalent  in  dots  per 

*We’ll  talk  about  how  to  set  the  font  search  path  later  in  this  chapter. 
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inch.  For  example,  the  16-inch  monitor  on  the  Sony  NEWS  workstation  has  an  advertised 
resolution  of  1280  x 1024  pixels.  The  actual  viewing  area  is  approximately  13  inches  wide 
by  10  inches  high.  Dividing  the  resolution  by  the  size,  you  come  up  with  a vertical  resolution 
of  102.4  dpi  and  a horizontal  resolution  of  98.5  dpi. 

The  Sun  19-inch  monitor,  by  contrast,  has  an  advertised  resolution  of  1 152  x 900.  The  hori- 
zontal and  vertical  dimensions  of  the  viewing  area  are  approximately  13.75  x 10.75  inches. 
This  yields  a resolution  of  about  84  dpi. 

What  happens  if  you  select  the  wrong  resolution  for  your  monitor?  Given  the  difference  in 
the  pixel  size,  the  same  size  font  will  appear  larger  or  smaller  than  the  nominal  point  size. 

For  example,  consider  the  75-  and  100-dpi  versions  of  the  24-point  charter  medium  italic 
font: 

-bitstream-charter-medium-i-normal — 25-240-75-75-p-136-iso8859-l 
-bit st ream-chart er-medium-i-normal — 33-240-100-100-p-179-iso8859-l 

If  you  look  at  the  pixel  size  field,  you  will  notice  that  the  height  of  the  75-dpi  version  is  25 
pixels,  while  the  height  of  the  100-dpi  version  is  33  pixels.  If  you  use  the  75-dpi  version  on 
the  Sun,  you  actually  get  something  closer  to  21.5  points  (75/84*24);  on  a 100-dpi  monitor, 
you  will  actually  get  something  closer  to  18  points  (75/100*24).  We  noticed  this  right  away 
when  we  first  began  using  the  Sony  workstation.  Because  of  its  higher  resolution,  the  font 
size  we  had  been  using  on  the  Sun  appeared  much  smaller. 

If  you  are  working  on  a lower-resolution  monitor,  you  can  take  advantage  of  this  artifact  to 
display  type  as  large  as  32  points  (the  size  that  a 24-point  100-dpi  font  will  appear  on  a 
75-dpi  monitor.)  Figure  5-6  shows  the  75-  and  100-dpi  versions  of  the  same  24-point  font,  as 
displayed  on  a Sun  workstation  with  a 19-inch  monochrome  monitor.  As  shown,  neither  is 
actually  24  points.  The  75-dpi  version  is  actually  21.5  points,  as  discussed  above;  the 
100-dpi  version  is  about  28.5  points.* 


-adobe-new  century  schoolbook-medium- r-n 

-adobe-new  century  schoolbook-m 


Figure  5-6.  The  1 00-dpi  version  of  a 24-point  font  appears  larger  on  a 75-dpi  monitor 


Note  that  the  logical  font  naming  convention  allows  for  different  horizontal  and  vertical  res- 
olution values.  This  would  allow  server  manufacturers  to  support  fonts  that  were  “tuned”  for 
their  precise  screen  resolution.  However,  the  fonts  that  are  shipped  with  the  generic  XI 1 dis- 
tribution all  use  the  same  horizontal  and  vertical  resolution. 


*Note  that  the  differences  are  exaggerated  further  in  printing  the  screen  dump  of  this  display,  xpr  lets  you  select  a 
scale  factor,  such  that  each  pixel  on  the  screen  appears  as  scale  pixels  in  the  printout.  Since  the  laser  printer  has  a 
300-dpi  resolution,  a scale  factor  of  4 would  produce  a true  scale  screen  dump  if  the  resolution  on  the  Sun  monitor 
were  truly  75  dpi  by  75  dpi.  Since  it  is  actually  84  by  84,  the  printed  image  is  enlarged  by  about  10%. 
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As  suggested  above,  this  resolution  may  not  exactly  match  the  actual  resolution  of  any  partic- 
ular screen,  resulting  in  characters  that  are  not  true  to  their  nominal  point  size.  In  the  case  of 
the  Sony  monitors,  the  actual  resolution  is  quite  close  to  the  design  of  the  100-dpi  fonts. 
However,  on  the  Sun  monitor,  neither  the  75-  nor  100-dpi  fonts  will  be  right.  (Of  course,  if 
you  are  using  the  XI  1/NeWS  server  rather  than  the  MIT  sample  server,  you  won’t  be  using 
bitmapped  fonts  at  all,  but  scalable  outline  fonts,  so  this  isn’t  a problem.) 

Other  Information  in  the  Font  Name 

What  we’ve  already  shown  summarizes  the  most  important  information  in  the  font  name. 
The  remaining  fields  are  explained  below: 

Foundry  Font  manufacturers  are  still  referred  to  as  foundries,  from  the  days  when 

type  was  cast  from  lead.  The  X font  naming  convention  specifies  that  the 
foundry  is  the  company  that  digitized  or  last  modified  the  font,  rather  than 
its  original  creator. 

For  the  fonts  contained  in  the  standard  X distribution,  the  foundry  is  not 
terribly  significant,  since  there  are  no  cases  where  the  same  font  family  is 
available  from  different  foundries.  However,  there  are  numerous  commer- 
cial font  families  available  from  more  than  one  foundry.  In  general,  the 
appearance  of  the  fonts  should  be  quite  similar,  since  the  font  family 
defines  the  design  of  the  typeface.  However,  there  may  be  some  small  dif- 
ferences in  the  quality  of  some  of  the  characters,  and  there  may  be  more 
significant  differences  in  the  font  metrics  (the  vertical  or  horizontal  mea- 
surements of  the  characters).  This  might  be  significant  for  a publishing 
application  that  was  using  the  bitmapped  font  for  a Wysiwyg  screen  display 
that  needed  to  match  the  fonts  in  a particular  laser  printer  or  typesetter. 

Set  width  A value  describing  a font’s  proportionate  width,  according  to  the  foundry. 

Typical  set  widths  include:  normal,  condensed,  semicondcnsed,  narrow, 
double  width.  All  of  the  Release  3 fonts  and  most  of  the  Release  4 fonts 
have  the  set  width  normal.  A few  of  the  Release  4 fonts  have  the  set  width 
semicondensed. 

Spacing  All  standard  Release  3 fonts  arc  either  m (monospace,  i.e.,  fixed- width)  or  p 

(proportional,  i.e.,  variable-width).  In  Release  4,  fonts  may  also  have  the 
spacing  characteristic  c (character  cell,  a fixed-width  font  based  on  the  tra- 
ditional typewriter  model,  in  which  each  character  can  be  thought  to  take 
up  the  space  of  a “box”  of  the  same  height  and  width).  As  mentioned  ear- 
lier, the  original  R2  fonts  were  of  this  type. 

Average  width  Mean  width  of  all  characters  in  the  font,  measured  in  tenths  of  a pixel. 

You’ll  notice,  if  you  look  back  at  Figure  5-2,  that  two  fonts  with  the  same 
point  size  (such  as  New  Century  Schoolbook  and  Times)  can  have  a very 
different  average  character  width.  This  field  can  sometimes  be  useful  if 
you  are  looking  for  a font  that  is  especially  wide  or  especially  narrow. 
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The  Clean  family  of  fonts  from  Schumacher  offers  several  fonts  in  the  same 
point  size,  but  with  different  average  widths.* 

Character  set  In  the  initial  illustration  of  the  font  naming  convention  (Figure  5-1),  we 
identified  the  character  set  as  a single  field.  If  you  look  more  closely, 
you’ll  realize  it  is  actually  two  fields,  the  first  of  which  identifies  the  orga- 
nization or  standard  registering  the  character  set,  the  second  of  which  iden- 
tifies the  actual  character  set. 

Most  fonts  in  the  standard  X distribution  contain  the  string  “iso8859-l”  in 
their  names,  which  represents  the  ISO  Latin- 1 character  set.  The  ISO 
Latin- 1 character  set  is  a superset  of  the  standard  ASCII  character  set, 
which  includes  various  special  characters  used  in  European  languages  other 
than  English.  See  Appendix  H of  Volume  Two,  Xlib  Reference  Manual , for 
a complete  listing  of  the  characters  in  the  ISO  Latin- 1 character  set. 

Note,  however,  that  the  symbol  font  contains  the  strings  “adobe- 
fontspecific”  in  this  position.  This  means  that  Adobe  Systems  defined  the 
character  set  in  this  font,  and  that  it  is  font-specific.  You  can  see  from  this 
example  that  the  usage  of  these  fields  is  somewhat  arbitrary. 

Style  Not  represented  in  the  example  or  in  most  R3  or  R4  font  names.  However, 

according  to  the  logical  font  convention,  the  style  of  a font  may  be  speci- 
fied in  the  field  between  set  width  and  pixels.  Some  of  the  possible  styles 
are  i (informal),  r (roman),  serif  and  sans  (serif).  Note  that  the  r for  roman 
may  also  be  used  in  the  slant  field. 

For  a complete  technical  description  of  the  font  naming  conventions,  see  the  X Consortium 
Standard,  X Logical  Font  Description  Conventions . This  document  is  available  as  part  of  the 
standard  MIT  X distribution,  and  is  reprinted  as  Appendix  M in  the  second  edition  of  Volume 
0,  X Protocol  Reference  Manual. 


Font  Name  Wildcarding 

Prior  to  Release  3,  the  use  of  wildcards  within  font  names  was  restricted  to  specifying  fonts 
to  list  with  xlsfonts.  If  you  are  running  Release  3 or  Release  4,  wildcarded  font  names  can 
also  be  used  to  specify  the  display  font  for  a client,  either  on  the  command  line  or  in  a 
resource  specification. 

An  asterisk  (*)  can  be  used  to  represent  any  part  of  the  font  name  string;  a question  mark  (?) 
can  be  used  to  represent  any  single  character.  You  can  usually  get  the  font  you  want  by  spec- 
ifying only  the  font  family,  the  weight,  the  slant,  and  the  point  size,  and  wildcarding  the  rest. 
For  example,  to  get  Courier  bold  at  14  points,  you  could  use  the  command  line  option: 

-fn  ' *courier-bold-r* 140* ' 


"■These  fonts  all  (incorrectly  to  our  minds)  have  a set  width  of  “normal."  They  should  be  distinguished  by  set  widths 
such  as  condensed,  semi-condensed,  etc.  Since  they  do  not,  they  can  be  distinguished  by  the  difference  in  their 
average  width. 
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That’s  starting  to  seem  a little  more  intuitive! 

However,  there  are  a number  of  “gotchas.” 

• First,  since  the  UNIX  shell  also  has  a special  meaning  for  the  * and  ? wildcard  characters, 
wildcarded  font  names  must  be  quoted.  This  can  be  done  by  enclosing  the  entire  font 
name  in  quotes  (as  in  the  previous  example),  or  by  “quoting”  each  wildcard  character  by 
typing  a backslash  before  it.  (If  you  don’t  do  this,  the  shell  will  try  to  expand  the  * to 
match  any  filenames  in  the  current  directory,  and  will  give  the  message  “No  match.”) 
Wildcards  need  not  be  quoted  in  resource  files. 

• Second,  if  the  wildcarded  font  name  matches  more  than  one  font,  the  server  will  use  the 
first  one  that  matches.  And  unfortunately,  because  the  names  are  sorted  in  simple  alpha- 
betical order,  the  bold  weight  comes  before  medium,  and  italic  and  oblique  slants  before 
roman.  As  a result,  a specification  like: 

-fn  ' ‘courier*' 

will  give  you  Courier  bold  oblique,  rather  than  the  Courier  medium  roman  you  might 
intuitively  expect. 

If  you  aren’t  sure  whether  your  wildcarded  name  is  specific  enough,  try  using  it  as  an 
argument  to  xlsfonts.  If  you  get  more  than  one  font  name  as  output,  you  may  not  get  what 
you  want.  Try  again  with  a more  specific  name  string. 

The  exception  to  this  rule  has  to  do  with  the  75dpi  and  100dpi  directories.  If  a wildcard 
matches  otherwise  identical  fonts  in  these  two  directories,  the  server  will  actually  use  the 
one  in  the  directory  that  comes  first  in  the  font  path.  This  means  that  you  should  put  the 
appropriate  directory  first  in  the  font  path.  (We’ll  tell  you  how  to  do  this  in  the  next  sec- 
tion.) Thereafter,  you  can  generally  wildcard  the  resolution  fields  (unless  you  specifically 
want  a font  from  the  directory  later  in  the  path).* 

• Third,  the  * wildcard  expansion  is  resolved  by  a simple  string  comparison.  So,  for 
example,  if  you  were  to  type: 

-fn  ' *courier-bold*r * 14 0 * ' 

instead  of: 

-fn  ' *cour ier-bold-r * 14 0 * ' 

(the  difference  being  the  asterisk  instead  of  the  hyphen  before  the  “r”  in  the  slant  field), 
the  “r”  would  also  match  the  “r”  in  the  string  “normal”  in  the  set  width  field.  The  result  is 
that  you  would  select  all  slants.  Since  o (oblique)  comes  before  r (roman),  and  you 
always  get  the  first  font  that  matches,  you’d  end  up  with  Courier  oblique. 


♦Unlike  xfontsel,  which  displays  fonts  in  the  order  of  wildcard  matches,  xlsfonts  will  always  list  fonts  in  straight  sort 
order,  with  the  sort  done  character-by-character  across  the  line.  Since  size  in  pixels  comes  before  point  size  in  the 
name,  and  the  size  in  pixels  of  the  100-dpi  fonts  is  larger  than  that  of  the  equivalent  75-dpi  font,  the  75-dpi  font  will 
always  be  listed  first  for  a given  point  size.  But  when  listing  more  than  one  point  size,  the  fonts  will  be  jumbled.  For 
example,  the  size  in  pixels  of  the  8 -point  charter  font  at  100-dpi  is  1 1,  so  it  will  come  after  the  10-point  charter  font  at 
75-dpi,  with  a size  in  pixels  of  10.  The  8-point  charter  font  at  75-dpi  gets  sorted  to  the  very  end  of  the  list,  since  to  a 
character-by-charactcr  sort,  its  size  in  pixels  (8)  looks  larger  to  the  size  in  pixels  of  even  the  largest  100-dpi  font  (the 
24-point,  with  a height  of  33  pixels). 
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The  trick  is  to  be  sure  to  include  at  least  one  of  the  hyphens  to  set  the  -r-  off  as  a separate 
field  rather  than  as  part  of  another  string. 

Even  though  a wildcarded  name  such  as: 

*cour*b*r-*140* 

should  get  you  14-point  Courier  bold  roman,  we  think  it  is  good  practice  to  spell  out  the 
font  family  and  the  weight,  and  to  use  hyphens  between  adjacent  fields.  As  usual,  there 
are  exceptions:  the  Lucida  family  really  has  three  subfamilies;  you  can  get  all  three  by 
specifying  the  family  as  “Lucida*”  rather  than  “Lucida-”;  and  you  might  certainly  want 
to  abbreviate  “New  Century  Schoolbook”  to  “New  Century*”  or  “* Schoolbook.” 

• Font  names  are  case-insensitive.  “Courier”  is  the  same  as  “courier.” 

Table  5-2  summarizes  the  values  you  can  use  to  specify  a unique  font  name  (assuming  only 
the  standard  fonts  are  loaded).  Choose  one  element  from  each  column.  Don’t  forget  to 
include  the  leading  and  trailing  asterisks,  and  the  hyphen  before  the  slant. 


Table  5-2.  Essential  Elements  of  a Font  Name 


* 

Family 

- 

Weight 

- 

Slant 

* 

Point  Size 

* 

Charter 

Courier 

Helvetica 

New  century 
schoolbook 

Symbol 

Times 

Fixed  (R4) 

Clean  (R4) 

OPEN  LOOK  (R4) 
Lucida  (R4) 

Terminal  (R4) 

Medium 

Bold 

Demibold 

r (roman) 
i (italic) 
o (oblique) 
ri  (reverse  italic) 

ro  (reverse  oblique) 
ot  (other) 

80  (8  pt.) 
100(10pt.) 
120  (12  pt.) 

140  (14  pt.) 

180  (18  pt.) 

240  (24  pt.) 

The  Font  Search  Path 

In  both  Release  3 and  Release  4,  fonts  are  stored  in  three  directories,  as  shown  in  Table  5-3. 
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Table  5-3.  Standard  Font  Directories,  Releases  3 and  4 


Directory 

Contents 

lusr/lib/Xl  1 /fonts/misc 

Release  3:  Six  fixed-width  fonts  (also  available  in 
Release  2),  plus  the  cursor  font. 

Release  4:  Sixty  fixed-width  fonts,  including  the  six 
available  in  Release  3,  the  cursor  font,  several  Clean 
family  fonts  provided  by  Schumacher,  a Kanji  font, 
Kana  fonts,  and  OPEN  LOOK  cursor  and  glyph 
fonts. 

lusr/lib/Xl  1 lfonts/75dpi 

Fixed-  and  variable-width  fonts,  75  dots  per  inch. 

/usr/lib/Xl  1 /fonts/ 100dpi 

Release  3:  The  Adobe  Charter  font  family,  100  dots 
per  inch. 

Release  4:  Fixed-  and  variable-width  fonts,  100  dots 
per  inch  (all  font  families). 

These  three  directories  (in  this  order)  comprise  X’s  default  font  path. 

Other  directories  can  be  added  to  the  font  search  path,  or  its  order  can  be  rearranged,  using 
xset  with  the  fp  option.  To  completely  replace  the  font  path,  simply  specify  a comma- 
separated  list  of  directories.  For  example,  to  pul  the  100dpi  directory  before  the  75dpi  direc- 
tory, you  might  enter: 

% xset  fp=  /usr/lib/Xll/fonts/raisc, /usr/lib/Xll/fonts/100dpi, \ 
/usr/lib/Xll/fonts/75dpi 

(Note  that  a space  must  follow  the  equal  sign,  and  that  the  example  above  is  broken  onto  two 
lines  escaped  with  a backslash  only  so  that  it  can  be  printed  within  the  page  margins.)  To 
restore  the  default  font  path,  type: 

% xset  fp  default 

Use  the  fp+  option  to  add  a directory  or  list  of  directories  to  the  end  of  the  font  path,  or  +f  p 
to  add  them  at  the  start.  Use  - fp  and  f p-  to  delete  directories  from  the  beginning  or  end  of 
the  font  path. 

For  a complete  listing  of  the  fonts  in  each  directory  and  samples  of  each  font,  refer  to  Appen- 
dix E,  Release  3 and  4 Standard  Fonts. 


The  fonts.dir  Files 


In  addition  to  font  files,  each  font  directory  contains  a file  called  fonts.dir.  The  fonts.dir  files 
serve,  in  effect,  as  databases  for  the  X server.  When  the  X server  searches  the  directories  in 
the  default  font  path,  it  uses  the  fonts.dir  files  to  locate  the  font(s)  it  needs. 
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Each  fonts.dir  file  contains  a list  of  all  the  font  files  in  the  directory  with  their  associated  font 
names,  in  two-column  form.  (The  first  column  lists  the  font  file  name  and  the  second  column 
lists  the  actual  font  name  associated  with  the  file.)  The  first  line  in  fonts.dir  lists  the  number 
of  entries  in  the  file  (i.e.,  the  number  of  fonts  in  the  directory). 

Example  5-1  shows  a portion  of  the  fonts.dir  file  from  the  Release  4 /usr/lib/Xl  1 /fonts/ 1 00dpi 
directory.  As  the  first  line  indicates,  the  directory  contains  200  fonts.  The  first  group  of  fonts 
listed  below  (up  to  the  second  ellipse)  are  available  as  of  Release  4.  They  are  all  Courier 
family  fonts.  (These  fonts  are  100-dpi  equivalents  of  fonts  that  in  Release  3 were  only  avail- 
able in  75-dpi.)  The  second  group  of  fonts  shown  in  the  list  below  (a  few  sizes  from  the 
Charter  family)  are  also  available  in  the  Release  3 100dpi  directory. 

Example  5- 1.  Subsection  of  the  Release  4 fonts.dir  file  in  /usr/lib/X  1 1 /fonts/1 00dpi 

200 


courBO08 . snf 
courBOlO . snf 
courBOl2 . snf 
courBOl 4 . sn  f 
courBOl8 . snf 
courB024 . snf 
courB08 . snf 
courBlO . snf 
courB12 . snf 
courBl 4 . snf 
courBl 8 . sn  f 
courB24 . snf 
courO08 . snf 
courOl 0 . snf 
cour012 . snf 
courOl 4 . snf 
courOl 8 . snf 
cour024 . snf 
courR08 . snf 
courRl 0 . snf 
courRl 2 . snf 
courRl 4 . snf 
courRl8 . snf 
courR24 . snf 


-adobe-courier-bold-o-normal — 11-80-100-1 00-m-60-i so8859-l 
-adobe-courier-bold-o-normal--14-100-100-l 00-m-90-iso8859-l 
-adobe-courier-bold-o-normal — 17-120-100-100-m-100-iso8859-l 
-adobe-courier-bold-o-normal --2 0-1 4 0-1 00-1 00-m-110-iso8 8 5 9-1 
-adobe-courier-bold-o-normal--25-180-100-100-m-150-iso8859-l 
-adobe-courier-bold-o-normal — 34-240-1 00-10 0-m-200-iso8 8 5 9-1 
-adobe-courier-bold-r-normal--ll-80-100-100-m-60-iso8859-l 
-adobe-courier-bold-r-normal--14-100-l 00-1 00-m-90-iso8859-l 
-adobe- courier-bo 1 d-r-normal— 1 7-120-10 0-1 00-m-100-iso8 8 5 9-1 
- adobe -courier-bold-r- no rmal--20-l 40-1 00-1 00-m-110~iso8 85 9-1 
-adobe-courier-bold-r-normal  — 25-18  0-10  0-100-m-150-iso8  85  9-1 
-adobe-courier-bo Id- r-normal — 34-240-100-100-m-200-iso8859-l 
-adobe-courier-medium-o-normal--ll-80-100-l 00-m-60-iso885  9-1 
-adobe-courier-medium-o-normal--14-100-100-100-m-90-iso8859-l 
-adobe-courier-medium-o-normal--17-120-100-100-m-100-iso8859-l 
-adobe-courier-medium-o-normal  — 2 0-1 4 0-1 00-1 0 0-m-ll 0-iso8  85  9-1 
-adobe -courier-medium-o- normal- -25-1 8 0-1 00-1 00 -m- 15 0-iso8 85  9-1 
-adobe-courier-medium-o-normal --3 4 -2 4 0-1 00-1 00-m-200-iso8 85 9-1 
-adobe-courier-medium-r-normal — ll-80-100-100-m-60-iso8859-l 
-adobe-courier-medium-r-normal  — 1 4 -1 0 0-1 0 0-1 00-m- 90-i so885  9-1 
-adobe-courier-medium-r-normal — 17-120-1 00-10 0-m-100-iso8 85 9-1 
-adobe-cour ier-medium- r-normal --2 0-1 4 0-1 00-1 00-m-l 10-i so 8 85  9-1 
-adobe-courier-medium-r-normal — 25-180-100-100-m-150-iso8859-l 
-adobe-courier-medium-r-normal — 34-240-100-1 00-m-200-i so8 85 9-1 


charBI 0 8 . snf 
charBUO . snf 
charBI12 . snf 
charBIl 4 . snf 
charBIl 8 . snf 
charBI24 . snf 


-bit st ream-char ter-bold-i -normal  — ll-80-100-100-p-68-iso8859-l 
-bi t st ream-chart er-bold-i -normal --1 4 -100-10 0-1 00-p- 8 6-iso8 85 9-1 
-bit stream- char ter-bold-i -normal --1 7-12 0-10 0-1 00-p-105-iso8 85 9-1 
-bit st ream-chart er-bold-i-normal--l 9-1 4 0-1 00-1 0 0-p-l 1 7-i so8  85  9-1 
-bitstream-charter-bold-i-normal--25-180-100-100-p-154-iso8859-l 
-bit  stream-chart er-bold-i -normal --3 3 -2 4 0-1 00 -100 -p-203-iso8 85 9-1 
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The  fonts.dir  files  are  created  by  the  mkfontdir  client  when  X is  installed,  mkfontdir  reads  the 
font  files  in  directories  in  the  font  path,  extracts  the  font  names,  and  creates  a fonts.dir  file  in 
each  directory.  If  fonts.dir  files  are  present  on  your  system,  you  probably  won’t  have  to  deal 
with  them,  or  with  mkfontdir  at  all.  If  the  files  are  not  present,  or  if  you  have  to  load  new 
fonts  or  remove  existing  ones,  you  will  have  to  create  files  with  mkfontdir.  Refer  to  Appen- 
dix A,  System  Management , for  details. 


Font  Name  Aliasing 

Another  way  to  abbreviate  font  names  is  by  aliasing  (that  is,  by  associating  fonts  with  alter- 
native names  of  your  own  choosing).  You  can  edit  or  create  a file  called  fonts. alias,  in  any 
directory  (or  multiple  directories)  in  the  font  search  path,  to  set  aliases  for  existing  fonts.  The 
X server  uses  both  fonts.dir  files  m<\  fonts. alias  files  to  locate  fonts  in  the  font  path. 

If  you  are  running  Release  3,  there  should  already  be  an  alias  file  in  the  misc  directory. 
Release  4 provides  a default  fonts.alias  file  for  each  of  the  three  font  directories.  Take  the 
time  to  look  at  the  contents  of  each  of  these  files,  since  many  of  the  existing  aliases  may  be 
easier  to  type  than  even  wildcarded  font  names.  You  can  also  add  aliases  to  the  file,  change 
existing  aliases,  or  even  replace  the  entire  file.  However,  this  should  be  done  with  caution. 
To  play  it  safe,  it’s  probably  a good  idea  merely  to  add  to  existing  fonts.alias  files.  If  you’re 
working  in  a multi-user  environment,  the  system  administrator  should  definitely  be  consulted 
before  aliases  are  added  or  changed.  Note  that  when  you  create  or  edit  a fonts.alias  file,  the 
server  does  not  automatically  recognize  the  aliases  in  question.  You  must  make  the  server 
aware  of  newly  created  or  edited  alias  files  by  resetting  the  font  path  with  xset. 

The  fonts.alias  file  has  a two-column  format  similar  to  the  fonts.dir  file:  the  first  column  con- 
tains aliases,  the  second  contains  the  actual  font  names.  If  you  want  to  specify  an  alias  that 
contains  spaces,  enclose  the  alias  in  double  quotes.  If  you  want  to  include  double  quotes  or 
other  special  characters  as  part  of  an  alias,  precede  each  special  symbol  with  a backslash. 

When  you  use  an  alias  to  specify  a font  in  a command  line,  the  server  searches  for  the  font 
associated  with  that  alias  in  every  directory  in  the  font  path.  Therefore,  a fonts.alias  file  in 
one  directory  can  set  aliases  for  fonts  in  other  directories  as  well.  You  might  choose  to  create 
a single  aliases  file  in  one  directory  of  the  font  path  to  set  aliases  for  the  most  commonly  used 
fonts  in  all  the  directories.  Example  5-2  shows  three  sample  entries  that  could  be  added  to  an 
existing  fonts.alias  file  (or  comprise  a new  one). 

Example  5-2.  Sample  fonts.alias  file  entries 

xterml2  -adobe -courier-medium-r-normal — 12-120-75-75-m-70-iso8859-l 

xterml 4 -adobe-courier-medium-r-normal  — 1 4-14  0-75-7  5-m-90-iso88  5 9-l 

xterml8  -adobe-courier-medium-r-normal — 18-180— 75-7 5-m-l 10-iso8859-l 

As  the  names  of  the  aliases  suggest,  these  sample  entries  provide  aliases  for  three  fonts  (of 
different  point  sizes)  that  are  easily  readable  in  xterm  windows.  (We  also  recommend  the 
fixed-width  font  stored  in  the  file  9xl5.snf*  in  the  misc  directory.)  You  can  also  use 

*In  Release  3,  the  actual  name  of  this  font  is  9x15.  The  Release  4 name  is: 

-misc-f ixed-medium-r-normal — 15-140-75-75-c-90-iso8859-l 
but  is  aliased  to  9x15  in  the  default  fonts.alias  file  in  the  misc  directory. 
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wildcards  within  the  font  names  in  the  right-hand  column  of  an  alias  file.  For  instance,  the 
alias  file  entries  above  might  also  be  written: 

xterml2  *courier-medium-r-*-120 * 

xterml4  *courier-medium-r-*-l 4 0 * 

xterml8  *courier-medium-r-*-180 * 

In  Release  2 of  X,  a font  name  is  equivalent  to  the  name  of  the  file  in  which  it  is  stored,  with- 
out the  .snf  extension.  In  the  previous  edition  of  this  book  (which  dealt  primarily  with 
Release  3 of  X),  we  recommended  a method  for  emulating  this  convention.  This  involved 
creating  a fonts.alias  file  containing  the  following  line  in  every  directory  in  the  font  path: 

FILE_NAMES_ALIASES 

You  could  then  use  a filename  (without  the  .snf  extension)  to  specify  a font.  Due  to  changes 
implemented  in  the  Release  4 server,  X Window  System  developers  are  now  discouraging 
this  practice. 

If  you  would  still  like  to  emulate  Release  2 conventions  in  Release  3 or  Release  4,  you  must 
explicitly  assign  every  font  name  an  alias  corresponding  to  the  name  of  the  file  in  which  it  is 
stored,  without  the  .snf  extension.  This  could  actually  be  done  rather  easily  by  editing  a copy 
of  each  fonts.dir  file  and  appending  the  copy  to  the  fonts.alias  file  in  the  same  directory.  (If 
you  are  running  Release  3,  remember  that  neither  the  75dpi  nor  the  100dpi  directory  has  a 
default  fonts.alias  file.  You  may  need  to  create  one,  rather  than  append  to  an  existing  one. 
These  aliases  could  also  be  appended  to  the  fonts.alias  file  in  the  misc  directory,  since  the 
server  searches  all  directories  in  the  font  path.) 

Once  the  server  is  made  aware  of  aliases,  you  can  specify  an  alias  on  the  command  line.  For 
example,  you  can  use  a font  name  alias  as  an  argument  to  xfd.  If  you’ve  used  an  alias  file  or 
files  to  emulate  the  Release  2 font  naming  conventions,  you  can  display  the  font  stored  in  the 
file  courR12.snf  using  the  command: 

% xfd  -fn  courR12 

A special  note  about  the  misc  directory:  when  X was  configured  for  your  system,  a 
fonts.alias  file  should  have  been  created  in  this  directory.  The  first  two  entries  in  this  file  are 
shown  below. 

fixed  -misc-f ixed-medium-r- semi condensed — 13-120-75-75-c-60-iso8859-l 

variable  -*-hel vet ica-bold-r-normal-* -*-120-*-*-* -*-*-* 

The  default  file  contains  an  additional  56  entries,  but  the  entries  pictured  above  are  particu- 
larly important.  The  aliases  called  “fixed”  and  “variable”  are  invoked  as  the  default  fonts  for 
many  clients.  The  “fixed”  font  can  be  thought  of  as  a system-wide  default.  The  “variable” 
font,  described  in  the  right-hand  column  as  a 12-point  bold  Helvetica  font,  is  used  as  the 
default  font  by  bitmap , as  well  as  by  other  clients.  If  this  file  is  removed  or  replaced,  when 
you  run  bitmap,  you’ll  get  an  error  message  that  the  server  cannot  open  the  variable  font,  and 
text  in  the  bitmap  window  will  display  in  the  smaller,  somewhat  less  readable  “fixed”  font. 

If  you  do  choose  to  edit  the  fonts.alias  file  in  the  misc  directory,  it  is  important  to  preserve  at 
least  these  two  aliases.  (As  we’ve  said,  it’s  probably  a better  idea  to  keep  all  the  default 
entries  and  merely  append  any  new  ones.) 
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If  you’re  running  Release  3,  the  fonts.alias  file  in  the  misc  directory  will  be  somewhat  differ- 
ent. The  Release  3 version  of  the  fonts.alias  file  in  the  misc  directory  is  comprised  of  only 
the  following  two  lines: 

fixed  6x13 

variable  *-helvet ica-bold-r-normal-*-*-l 4 0-* 

Regardless  of  what  edits  you  make  to  the  file,  the  line  specifying  the  variable  alias  must  not 
be  changed. 

The  variable  font  is  slightly  larger  in  Release  3 (14-point)  than  in  Release  4 (12-point).  If 
you  examine  the  Release  3 alias  file  a little  more  closely,  you  may  notice  that  the  first  line 
contains  an  incorrect  alias  specification.  Remember,  in  Release  3,  fixed  is  actually  the  name 
of  the  default  system  font — it  is  not  an  alias.  The  first  column  should  contain  aliases  and  the 
second  column  should  contain  proper  font  names.  However,  6x13  is  not  a proper  font  name. 
It  is  actually  the  name  of  the  file  that  contains  the  font  named  “fixed.”  You  can  specify  fixed 
as  a font  on  the  command  line  and  it  will  work — but  as  a font  name,  not  an  alias. 

Making  the  Server  Aware  of  Aliases 

After  you  create  (or  update)  an  alias  file,  the  server  does  not  automatically  recognize  the 
aliases  in  question.  You  must  make  the  server  aware  of  newly  created  or  edited  alias  files  by 
“rehashing”  the  font  path  with  xset.  Enter: 

% xset  fp  rehash 

on  the  command  line.  Th exset  option  fp  (font  path)  with  the  rehash  argument  causes  the 
server  to  reread  the  fonts.dir  and  fonts.alias  files  in  the  current  font  path.  You  need  to  do  this 
every  time  you  edit  an  alias  file.  (You  also  need  to  use  xset  if  you  add  or  remove  fonts.  See 
Appendix  A,  System  Management , for  details.) 


Utilities  for  Displaying  Information  about  Fonts 

We’ve  already  mentioned  xlsfonts , which  simply  displays  the  names  and  aliases  of  available 
fonts.  In  addition,  xfd  can  be  used  to  display  the  full  character  set  of  a particular  font,  and 
xfontsel  can  be  used  to  interactively  preview  and  select  a font  for  use  in  another  window. 


The  Font  Displayer:  xfd 

If  you’re  unfamiliar  with  general  appearance  of  a particular  font,  we’ve  included  pictures  of 
some  representative  fonts  in  Appendix  E,  Release  3 and  4 Standard  Fonts. 

You  can  also  display  the  characters  in  a font  using  the  xfd  (font  displayer)  client.  Note  that 
since  Release  3,  xfd  has  taken  an  option,  -f  n,  before  the  font  name.  For  example,  to  display 
the  default  system  font,  a 6x13  pixel  fixed- width  font  known  as  fixed*,  enter: 

*In  Release  3,  fixed  is  a legitimate  font  name.  In  Release  4,  it  is  an  alias  for  a longer  font  name  that  follows  the  con- 
ventions outlined  above. 
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% xfd  -fn  fixed  & 


The  xfd  window  will  display  the  specified  font  as  shown  in  Figure  5-7. 
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Figure  5-7.  Fixed  font,  6x13  pixels 


This  figure  depicts  the  Release  4 version  of  xfd,  which  has  been  greatly  enhanced  since 
Release  3.  The  font  name  is  now  displayed  across  the  top  of  the  window.  (This  is  the  actual 
font  name,  which  we  specified  on  the  command  line  by  the  alias  fixed.)  Three  command  but- 
tons have  also  been  added  to  the  application  in  Release  4.  They  appear  in  the  upper-left  of 
the  window,  below  the  font  name.  If  the  font  being  displayed  doesn’t  fit  within  a single  xfd 
screen,  Prev  Page  and  Next  Page  allow  you  to  scroll  through  multiple  screens.  (The  horizon- 
tal and  vertical  dimensions  of  the  window  can  vary  slightly  to  accommodate  different  fonts, 
but  certain  fonts  will  still  require  multiple  screens.)  The  Quit  button  causes  the  application  to 
exit,  though  this  can  also  be  done  by  typing  q or  Q anywhere  within  the  window. 

In  addition  to  displaying  a font,  xfd  also  allows  you  to  display  certain  information  about  the 
individual  characters.  But  before  we  examine  these  capabilities,  let’s  take  a closer  look  at 
the  way  the  characters  in  a font  are  identified  and  how  the  rfd  window  makes  use  of  this 
information. 

Within  a font,  each  character  is  considered  to  be  numbered.  The  xfd  client  displays  a font’s 
characters  in  a grid.  By  default,  the  first  character  of  the  font  appears  in  the  upper-left  posi- 
tion; this  is  character  number  0.  The  two  text  lines  above  the  grid  identify  the  upper-left 
character  and  the  range  of  characters  in  the  window,  by  character  number(s)  both  in  hexade- 
cimal and  in  decimal  notation  (in  parentheses  following  the  hex  character  number). 

You  can  specify  a character  other  than  character  number  0 to  be  in  the  first  position  in  the 
window  using  the  -start  option.  For  example,  if  you  enter  the  following  command  line: 

% xfd  -start  15  -fn  fixed  & 

the  xfd  window  begins  with  character  number  15. 
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Notice  the  instruction  Select  a character  below  the  command  buttons.  To  display 
information  about  a particular  character,  click  any  pointer  button  within  its  grid  square. 
Statistics  about  the  character’s  width,  left  bearing,  right  bearing,  ascent,  and  descent  are 
displayed  where  the  line  Select  a character  previously  appeared. 

If  you  are  running  the  Release  3 version  of  xfd,  read  the  section  “Release  3 xfd.” 

The  xfd  client  is  most  useful  when  you  have  an  idea  what  font  you  might  want  to  display.  If 
you  don’t  have  a particular  font  in  mind  or  would  like  to  survey  the  possibles,  the  xfontsel 
client  (available  as  of  Release  4)  allows  you  to  preview  a variety  of  fonts  by  specifying  each 
component  of  the  font  name  using  a different  menu.  See  the  section  “Previewing  and  Select- 
ing Fonts:  xfontsel”  later  in  this  chapter. 

Release  3 xfd 

The  Release  3 version  of  xfd  is  not  as  flexible  or  as  self-explanatory  as  the  Release  4 version. 
It  offers  no  command  buttons,  no  line  identifying  the  font  name,  and  no  obvious  scrolling 
capabilities.  However,  it  is  still  very  useful  for  looking  at  a particular  font. 

Like  the  Release  4 version,  by  default  the  Release  3 xfd  displays  character  number  0 of  the 
font  at  the  upper  left  of  the  window.  To  see  a character’s  number,  move  the  pointer  to  the 
desired  character  and  click  the  middle  button.  That  character’s  number  is  displayed  both  in 
decimal  and  in  hexadecimal  notation  at  the  bottom  of  the  window,  as  in  the  following: 

85.  (0x55)  : 

This  version  of  x fd  also  accepts  the  -start  option,  which  lets  you  specify  the  first  character 
of  the  font  that  appears  at  the  upper  left  of  the  window. 

Every  character  in  the  font  may  not  fit  in  the  window  at  once.  Though  this  version  of  the 
application  does  not  feature  the  handy  command  buttons  introduced  at  Release  4,  you  can 
still  view  the  obscured  characters.  To  see  additional  characters,  move  the  pointer  to  the  xfd 
window  and  click  the  third  (usually  the  right)  mouse  button.  The  next  window  full  of  charac- 
ters is  displayed.  To  see  the  previous  window  of  characters,  click  the  first  (usually  the  left) 
mouse  button,  xfd  beeps  if  an  attempt  is  made  to  go  back  past  the  first  (0)  character. 

The  Release  3 rfd  also  provides  statistics  about  the  individual  characters  in  a font,  but  you 
must  run  the  client  with  the  -verbose  option  to  access  this  information.  Then,  to  see 
information  about  a character’s  width,  left  bearing,  right  bearing,  ascent,  and  descent,  move 
the  pointer  to  the  desired  character  and  click  the  second  (usually  the  middle)  button.  The 
information  is  displayed  in  a portion  of  the  window  below  the  character  grid. 

To  display  the  minimum  or  maximum  values  taken  by  each  of  these  fields  over  the  entire 
font,  move  the  pointer  to  the  desired  character  and  type  a less  than  symbol  (<)  to  display  the 
minimum  values  or  a greater  than  symbol  (>)  to  display  the  maximum.  Information  similar 
to  the  following  is  displayed  below  the  grid: 

maximum  bounds: 

left  bearing  = 2,  right  bearing  = 6 
ascent=  10  , descent  = 3 
width  = 6 
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To  delete  an  xfd  window  that  is  running  in  the  background,  you  can  move  the  pointer  to  the 
window  and  type  either  q,  Q,  or  Control-C. 


Previewing  and  Selecting  Fonts:  xfontsel 

The  xfontsel  client,  available  as  of  Release  4,  provides  a font  previewer  window  in  which  you 
select  the  font  to  view  using  14  menus  corresponding  to  the  14  components  of  a font  name. 
By  specifying  various  font  name  components,  you  can  take  a look  at  a variety  of  fonts.  This 
is  particularly  useful  if  you  are  trying  to  pick  good  display  fonts  and  you  don’t  have  a very 
clear  idea  what  type  of  font  would  be  best.  Rather  than  running  several  instances  of  xfd,  you 
can  dynamically  change  the  font  displayed  in  the  xfontsel  window  by  changing  the  font  name 
components.  (Despite  the  flexibility  of  xfontsel,  it’s  certainly  not  practical  to  preview  all  of 
the  available  fonts.  If  you  have  no  idea  what  particular  font  families  look  like,  see  the  dis- 
cussion earlier  in  this  chapter,  or  refer  to  Appendix  E,  Release  3 and  4 Standard  Fonts,  for 
complete  listings.)* 

Once  you’ve  displayed  the  desired  font  using  the  menus,  you  can  make  the  name  of  that  font 
the  PRIMARY  text  selection  by  clicking  on  the  window’s  select  button.  (Selecting  text  is 
described  in  Chapter  4,  The  xterm  Terminal  Emulator)  You  can  then  paste  the  font  name 
into  another  window  using  the  pointer:  onto  a command  line,  into  a resource  file,  etc.  Mak- 
ing a font  name  the  PRIMARY  selection  also  enables  you  to  choose  that  font  from  the  xterm 
VT  Fonts  menu,  described  in  Chapter  4. 

Previewing  Fonts  with  the  xfontsel  Menus 

To  run  xfontsel,  enter  the  following  command  in  an  x term  window: 

% xfontsel  & 

If  your  system  is  using  the  standard  Release  4 fonts,  the  xfontsel  window  initially  displays  a 
bold,  constant-width,  7x13  pixel  font,  from  the  misc  font  directory,  as  shown  in  Figure  5-8. 
This  is  the  first  font  in  the  default  font  search  path. 

The  upper-left  comer  of  the  xfontsel  window  features  two  command  buttons:  quit  and 
select.  As  we’ve  explained,  clicking  on  select  (with  the  first  pointer  button)  makes  the  font 
displayed  in  the  window  the  PRIMARY  text  selection.  Obviously,  quit  causes  the  applica- 
tion to  exit. 

Below  the  command  buttons  is,  in  effect,  a generic  font  name  or  font  name  template.  It  is 
divided  into  14  fields  corresponding  to  the  14  parts  of  a standard  font  name.  Each  field  is  an 
abbreviation  for  one  part  of  a font  name.  Take  a look  again  at  the  sample  font  name  in  Figure 


♦To  our  minds,  the  major  drawback  of  xfontsel  is  that  it  shows  you  only  the  first  font  that  matches  a given  wildcarded 
font  name.  A far  better  interface  would  list  all  of  the  matching  fonts,  so  that  you  could  compare  and  choose  the  one 
that  most  suited  your  needs.  There  is  no  way  in  the  standard  X distribution  to  display  the  appearance  of  a group  of 
fonts.  To  produce  the  figures  in  this  book,  we  had  to  write  such  a program,  which  we  called  xshowfonts.  The  pro- 
gram has  since  been  posted  to  comp  .sources  jc,  and  a listing  appears  in  Appendix  E. 
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| quit  1 1 select 


474  fonts  match 


-fndry-fmly-wght-siant-sWdth-adstyl-pxIsz-ptSz-resx-resy-spc-avgWdth-rgstry-encdng 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 

abcdefghijklmnopqrstuvwxyz 

0123456789 


Figure  5-8.  xfontse!  window  displaying  7x13  bold  font 

5-1  to  refresh  your  memory  as  to  the  components.  Each  of  the  fields  in  the  xfontsel  window 
is  actually  the  handle  to  a menu,  which  lets  you  specify  this  part  of  the  font  name. 

To  get  a clearer  idea  of  how  this  works,  move  the  pointer  onto  the  generic  font  name,  specifi- 
cally onto  the  first  field,  fndry.  (This  is  an  abbreviation  for  the  first  part  of  a font  name,  the 
foundry.)  When  you  place  the  pointer  on  fndry,  the  field  title  should  be  highlighted  by  a box. 
You  can  then  display  a menu  of  foundry  names  by  pressing  and  holding  down  the  first  pointer 
button,  as  in  Figure  5-9. 

Notice  that  the  first  choice  is  the  asterisk  (*)  wildcard  character.  This  is  the  first  choice  on  all 
of  the  menus  and  thus  allows  you  to  include  wildcards  in  the  font  name  you  specify,  rather 
than  explicitly  selecting  something  from  all  14  menus. 

To  specify  a font  name  component  (i.e.,  make  a selection  from  the  menu),  continue  to  hold 
down  the  first  pointer  button  and  move  the  pointer  down  the  menu.  As  the  pointer  rests  on 
each  menu  item,  it  is  highlighted  by  reverse  video.  To  select  a highlighted  menu  item, 
release  the  first  pointer  button. 

The  line  below  the  font  name  menus  represents  the  actual  font  name.  When  you  first  run 
xfontsel,  all  of  these  fields  contain  wildcard  characters  because  no  menu  selections  have  been 
made.  The  number  of  fonts  matched  by  the  font  name  is  displayed  in  the  upper-right  comer 
of  the  window.  The  number  of  fonts  matched  initially  depends  on  the  number  of  fonts  with 
this  naming  convention  available  on  your  system.  In  this  example,  474  fonts  match.  (Since 
this  line  of  wildcards  can  match  any  14  part  font  name,  the  server  chooses  the  first  font  in  the 
font  path  that  reflects  this  naming  convention.) 
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quit  1 1 select  | 474  fonts  match 

-fndry-fmly-\ 

* ^ 

misc 

schumacher 

sony 

sun 

adobe 

b&h 

bitstream 

dec 

vght-slant-sWdth-adstyl-pxlsz-ptSz-resx-resy-spc-avgWdth-rgstry-encdng 

■ 

■ 

■ 

■ 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

abcdefghijklmnopqrstuvwxyz 

0123456789 

Figure  5-9.  xfontse!  window  with  foundry  menu  displayed 

When  you  select  a font  name  component  from  one  of  the  14  menus,  the  component  appears 
in  the  actual  font  name,  and  the  xfontsel  window  displays  the  first  font  that  matches  this 
name.  For  example,  say  we  select  adobe  from  the  fndry  menu,  the  xfontsel  window  would 
look  like  Figure  5-10. 


quit  select 


204  fonts  match 


-fndry-fmly-wght-slant-sWdth-adstyl-pxlsz-ptSz-resx-resy-spc-avgWdth-rgstry-encdng 


■ adobe  - * 


ABCDEF  GHI JKLMN  O P Q RS T UVWX  Y Z 
abcdefghijklmn opqr  s t uvwxy z 
0123456789 


Figure  5-10.  xfontsel  after  choosing  Adobe  from  the  foundry  menu 
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The  font  name  is  now: 

-adobe-*-*-*-*-*-*-*-*-*-*-*-*-* 

and  the  window  displays  the  first  font  in  the  font  path  to  match  this  wildcarded  name.  In  this 
case,  the  first  font  to  match  is  a 12-point  bold  Oblique  Courier  font,  which  is  stored  in  the  file 
courBOlO.snf  and  has  the  actual  font  name: 

-adobe-courier-bold-o-normal-*-10-l 00-75-75-m-60-iso8859-l 

Once  you  make  a selection  from  one  menu,  the  number  of  possible  fonts  matched  by  the 
name  changes.  (Notice  the  line  204  fonts  match  in  the  upper-right  comer  of  the  win- 
dow.) Choosing  one  font  name  component  also  eliminates  certain  choices  on  other  menus. 
For  example,  after  you  select  Abobe  as  the  foundry,  the  possible  choices  for  font  family  (the 
second  menu,  fmly)  are  narrowed  from  14  to  5 (not  counting  the  asterisk).  Again  display  the 
fmly  menu  using  the  first  pointer  button.  The  available  choices  for  font  family  appear  in  a 
regular  typeface;  the  items  that  cannot  be  selected  appear  in  a lighter  typeface.  Families  such 
as  Clean,  Lucida,  and  Charter  are  in  a lighter  typeface  because  none  of  the  standard  X fonts 
provided  by  Adobe  are  from  these  families.  Adobe  fonts  in  the  standard  X distribution  are 
limited  to  the  five  families  Courier,  Helvetica,  New  Century  Schoolbook,  Symbol,  and  Times, 
and  these  are  the  items  available  on  the  fmly  menu. 

In  order  to  display  a particular  font,  you’ll  probably  have  to  make  selections  from  several  of 
the  menus.  As  described  earlier  in  the  section  “Font  Name  Wildcarding,”  we  suggest  you 
explicitly  select  at  least  the  following  parts  of  the  font  name: 

• Font  family 

• Weight 

• Slant 

• Point  size 

Thus,  you  would  make  selections  from  the  fmly,  wght,  slant,  and  ptSz  menus. 

You  can  also  use  the  -pattern  option  with  a wildcarded  font  name  to  start  out  with  a more 
limited  range  of  options.  For  example,  if  you  typed: 

% xfontsel  -pattern  ' *courier-bold-o-*' 

you’d  start  out  with  the  pattern  you  specified  in  the  filename  template  part  of  the  xfontsel  dis- 
play. You  could  then  simply  select  from  the  ptSz  menu  to  compare  the  various  point  sizes  of 
Courier  bold  oblique  until  you  found  the  one  you  wanted. 

Note  that  if  the  pattern  you  specify  to  xfontsel  matches  more  than  one  font,  the  one  that  is 
displayed  (the  first  match  found)  is  the  one  that  the  server  will  use.  This  is  in  contrast  to 
xlsfonts,  which  sorts  the  font  names.  You  can  always  rely  on  xfontsel  to  show  you  the  actual 
font  that  will  be  chosen  given  any  wildcard  specification. 
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Selecting  a Font  Name 


Once  you  compose  the  name  of  the  font  you  want  by  making  selections  from  the  menus,  the 
corresponding  font  is  displayed  in  the  xfontsel  window.  Then  you  can  select  that  font  name 
by  clicking  on  the  select  command  button  with  the  first  pointer  button.  The  font  name 
becomes  the  PRIMARY  text  selection  and  thus  can  be  pasted  in  another  window  using  the 
second  (usually  the  middle)  pointer  button,  as  described  in  Chapter  4,  The  xterm  Terminal 
Emulator. 

You  might  paste  the  font  name  on  a client  command  line  in  an  xterm  window,  in  order  to 
specify  it  as  the  client’s  display  font.  (See  Chapter  8,  Command  Line  Options .)  You  might 
paste  it  into  a resource  file  such  as  Xresources  to  specify  it  as  the  default  font  for  a client  or 
some  feature  of  a client  (such  as  a menu).  (See  Chapter  9,  Setting  Resources , for  more 
information.) 

Less  obviously,  once  a font  name  is  made  the  PRIMARY  text  selection,  it  can  be  toggled  as 
the  xterm  display  font  using  the  Selection  item  of  the  xterm  VT  Fonts  menu.  The  Selection 
menu  item  can  only  be  chosen  from  the  VT  Fonts  menu  when  there  is  a PRIMARY  text  selec- 
tion. (Otherwise,  the  menu  item  appears  in  a lighter  typeface,  indicating  that  it  is  not  avail- 
able.) If  the  PRIMARY  text  selection  is  a valid  font  name  (as  it  is  when  you’ve  pressed  the 
select  button  in  the  xfontsel  window),  the  xterm  window  displays  in  that  font.  (In  cases 
where  the  PRIMARY  selection  is  not  a valid  font  name,  the  xterm  display  font  does  not 
change.) 

By  default,  xfontsel  displays  the  lower  and  uppercase  letters  a through  z and  the  digits  0 
through  9.  You  can  specify  alternative  sample  text  using  the  -sample  option.  For  more 
information  about  this  and  other  options,  see  the  xfontsel  reference  page  in  Part  Three  of  this 
guide. 


Changing  Fonts  in  xterm  Windows 

As  discussed  in  Chapter  4,  The  xterm  Terminal  Emulator , xterm  includes  a VT  Fonts  menu 
that  allows  you  to  change  fonts  on  the  fly.  We  discussed  most  of  the  menu  entries  in  Chapter 
4.  However,  two  of  the  many  items  require  a greater  understanding  of  font  naming  than  we’d 
covered  by  that  point.  So  we’ve  saved  them  until  now. 

The  Great  Escape 

Though  it  is  by  no  means  obvious,  xterm  allows  you  to  change  the  display  font  by  sending  an 
escape  sequence,  along  with  the  new  font  name,  to  the  terminal  window.  Once  you  change 
the  font  in  this  way,  the  Escape  Sequence  item  on  the  xterm  VT  Fonts  menu  becomes  avail- 
able and  choosing  it  toggles  the  font  you  first  specified  with  the  escape  sequence.  (In  effect, 
whatever  font  you  specify  using  the  escape  sequence  is  stored  in  memory  as  the  menu’s 
Escape  Sequence  font  selection.) 

You  send  an  escape  sequence  to  the  terminal  window  by  using  the  UNIX  echo(l)  command. 
The  escape  sequence  to  change  the  xterm  display  font  is  comprised  of  the  following 
keystrokes: 
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Esc  ] 50  ; fontname  Control-G 

To  clarify,  these  keystrokes  are:  the  Escape  key,  the  right  bracket  (]),  the  number  50,  a semi- 
colon (;),  a fontname,  and  the  Control-G  key  combination.  We’ve  shown  the  keystrokes 
with  spaces  between  them  for  readability,  but  when  you  type  the  sequence  on  the  command 
line,  there  should  be  no  spaces.  Note  also  that  to  supply  this  sequence  as  an  argument  to 
echo,  you  must  enclose  it  in  quotes: 

% echo  "Esc] 50;  fontnameControl-G" 

These  are  the  literal  keys  you  type.  However,  be  aware  that  when  you  type  these  keys  as 
specified,  the  command  line  will  not  look  exactly  like  this.  Certain  keys,  like  Escape,  and 
key  combinations,  like  Control-G,  are  represented  by  other  symbols  on  the  command  line. 
When  you  type  the  key  sequence  above,  the  command  line  will  actually  look  like  this: 

% echo  [] 50;  fontname^G" 

Typing  the  Escape  key  generates  the  A[  symbol  and  typing  the  Control-G  key  combination 
generates  "G.  You  can  use  a full  fontname,  an  alias,  or  a wildcarded  font  specification  as  the 
fontname.  You  should  be  aware  that  if  the  wildcarded  specification  matches  more  than  one 
font,  you  will  get  the  first  font  in  the  search  path  that  matches.  For  example: 

% echo  " ~ [ ] 50;  *couri«r*''G" 

will  get  you  a 10-point  courier  bold  oblique.  The  advantage  of  being  able  to  change  the  dis- 
play font  with  an  escape  sequence  is  that  it  allows  you  to  add  another  font  to  your  choices  on 
the  fly.*  Changing  the  fonts  associated  with  the  Tiny,  Small,  Medium,  and  Large  menu  items 
is  a more  laborious  process.  It  involves  specifying  other  fonts  in  a resource  file,  making 
those  resources  available  to  the  server,  and  then  running  another  xterm  process.  (See  Chapter 
9,  Setting  Resources,  for  more  information.)  However,  you  can  change  the  font  specified  by 
the  Escape  Sequence  menu  item  as  often  as  you  want  during  the  current  xterm  process,  sim- 
ply by  typing  the  escape  sequence  described  above. 

Now  that  we’ve  looked  at  the  mechanics  of  the  escape  sequence,  let’s  consider  its  practical 
use.  Say  you  want  to  run  a program  in  an  xterm  window  and  you  want  to  be  able  to  read  the 
output  easily,  but  you  would  like  the  window  to  be  moderately  small.  You  discover  that  tog- 
gling the  Medium  font,  the  8x13  font  by  default,  makes  the  window  a good  size,  but  the 
typeface  is  too  light  to  be  read  easily.  (We  presume  you  are  using  the  default  menu  fonts  and 
have  not  customized  them  using  a resource  file.)  You  could  dynamically  change  the  display 
font  to  a bold  font  of  the  same  size  by  entering  the  following  command  line: 

% echo  "Esc] 50; 8xl3boldControl-G" 

The  xterm  font  becomes  the  desired  8xl3bold,  a good  choice;  in  addition,  the  Escape 
Sequence  item  of  the  VT  Fonts  menu  becomes  available  for  selection.  This  menu  item 
allows  you  to  toggle  the  8xl3bold  font  at  any  time  during  the  xterm  process.  Thus,  you 
could  switch  back  to  any  of  the  other  fonts  available  on  the  menu  (Small,  Large,  etc.)  and 
then  use  Escape  Sequence  to  again  select  8xl3bold. 


^Specifying  a font  with  an  escape  sequence  affects  only  the  current  xterm  window  and  enables  only  that  window’s 
Escape  Sequence  menu  selection. 
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This  font  will  remain  the  Escape  Sequence  font  for  the  duration  of  the  xterm  process,  unless 
you  again  change  the  display  font  with  an  escape  sequence.  If  you  enter  another  font  name 
using  the  escape  sequence  described  above,  the  window  will  display  in  that  new  font  and  the 
Escape  Sequence  menu  item  will  toggle  it. 

The  Selection  Menu  Item 

The  Selection  menu  item  allows  you  to  toggle  a font  whose  name  you’ve  previously 
“selected.”  The  font  name  could  be  selected  with  the  pointer,  for  example,  from  xlsfonts  out- 
put, using  the  “cut-and-paste”  techniques  described  in  Chapter  4,  The  xterm  Terminal  Emula- 
tor. It  is  far  more  likely,  though,  that  you  would  use  this  menu  item  after  selecting  a font 
with  xfontsel.  This  menu  item  was  clearly  designed  with  xfontsel  in  mind.  (If  no  text  is  cur- 
rently selected,  this  menu  item  is  “grayed  out,”  indicating  that  it  is  unavailable.) 

The  main  limitation  of  this  menu  item  is  that  it  uses  the  last  text  selected  as  the  font  name, 
regardless  of  what  that  text  is.  If  you  select  a font  name,  that  name  is  only  available  through 
Selection  until  you  use  the  pointer  to  select  other  text.  Since  cutting  and  pasting  text  is  one 
of  the  most  useful  features  of  xterm,  you  will  probably  be  making  frequent  selections.  If  the 
last  selected  text  was  not  a valid  font  name,  toggling  Selection  will  not  change  the  display 
font,  and  a beep  will  inform  you  that  the  toggle  failed. 


Release  2 versus  Subsequent  Release  Fonts 

The  primary  intent  of  this  guide  is  to  describe  the  features  of  Release  4 of  the  standard  X 
Window  System  shipped  by  MIT.  However,  we  assume  that  many  people  are  still  using 
Release  3 and  that  some  are  still  using  Release  2.  The  available  display  fonts,  font  naming 
conventions,  and  possible  system  administration  tasks  supporting  fonts  changed  radically 
from  Release  2 to  Release  3.  For  those  who  have  been  using  Release  2 display  fonts,  switch- 
ing to  Release  3 or  4 may  take  some  adjustment.  The  following  two  sections  will  acquaint 
you  with  the  differences  between  Release  2 fonts  and  the  fonts  provided  in  later  releases  and 
show  you  how  to  work  effectively  with  the  fonts  you  have. 


Font  Specification  in  Release  2 

All  Release  2 screen  fonts  are  stored  in  a single  directory  called  /usr/lib/Xl  1 /fonts  * If  you 
do  a listing  of  that  directory,  you’ll  see  a list  of  filenames  with  .snf  extensions.  These  are  the 
font  files.  In  Release  2,  the  name  of  a font  is  equivalent  to  the  name  of  the  file  in  which  it  is 
stored,  without  the  .snf  extension. 

Thus,  the  file  fg-16.snf  contains  the  font  fg- 16.  To  create  an  xterm  window  in  which  text  will 
be  displayed  with  the  font  named  fg-16,  type  the  command  line: 

*At  Release  3,  most  Release  2 fonts  were  moved  from  the  standard  distribution  of  X to  the  user-contributed 
distribution. 
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% xrtarm  -fn  fg-16  & 

You  can  find  out  which  fonts  are  available  by  using  the  xlsfonts  client.  If  you  type 
xls  fonts  in  an  x term  window,  you  should  get  a list  of  the  available  fonts,  which  are  sum- 
marized in  Table  5-4. 


Table  5-4.  Fonts  in  the  Standard  Distribution,  Release  2 


Fixed-width  Fonts 

Variable-width  Fonts 

6x10 

fgbl-25 

oldera 

apl-s25 

hbr-s40 

vg-25 

vr-30 

6x12 

fgbl-30 

rot-sl6 

arrow3 

krivo 

vg-31 

vr-31 

6x13 

fgi-20 

sans 12 

chp-s25 

met25 

vg-40 

vr-40 

8x13 

fgil-25 

sansbl2 

chs-s50 

mit 

vgb-25 

vrb-25 

8xl3bold 

fgs-22 

sansil2 

cursor 

plunk 

vgb-31 

vrb-30 

9x15 

fixed 

seriflO 

cyr-s25 

runlen 

vgbc-25 

vrb-31 

erturz 

fqxb-25 

serif  12 

cyr-s30 

stan 

vgh-25 

vrb-35 

dancer 

fr-25 

serifblO 

cyr-s38 

sub 

vgi-20 

vrb-37 

fg-13 

fr-33 

serifbl2 

ent 

subsub 

vgi-25 

vri-25 

fg-16 

frl-25 

serifilO 

fcor-20 

sup 

vgi-31 

vri-30 

fg-18 

fr2-25 

serifil2 

fgb-13 

supsup 

vgl-40 

vri-31 

fg-20 

fr3-25 

stempl 

fgb-25 

sym-s25 

vgvb-31 

vri-40 

fg-22 

frb-32 

swd-s30 

fri-33 

sym-s53 

vmic-25 

vsg-114 

fg-25 

ipa-s25 

vtbold 

fril-25 

variable 

vply-36 

vsgn-57 

fg-30 

lat-s30 

vtsingle 

ger-s35 

vbee-36 

vr-20 

vshd-40 

fg-40 

micro 

xif-s25 

grk-s25 

vctl-25 

vr-25 

vxms-37 

fgl-25 

grk-s30 

vg-13 

vr-27 

vxms-43 

hbr-s25 

vg-20 

These  fonts  are  divided  into  fixed-width  fonts  (typewriter  style)  and  variable-width 
fonts  (proportional).  Use  only  fixed-width  fonts  for  text  in  an  xterm  window.  (Variable- 
width  fonts  would  be  treated  as  fixed-width,  and  would  be  spaced  unevenly.)  Use  variable- 
width  fonts  only  with  programs  designed  to  use  them,  such  as  a PostScript  previewer  or 
Wysiwyg*  editor. 

The  characters  in  each  font  can  be  displayed  using  the  xfd  client.  To  display  the  default  font, 
a 6x13  pixel  fixed-width  font  named  fixed , type: 

% xfd  fixed 

The  resulting  xfd  window  is  shown  in  Figure  5-11. 

When  a font  is  referenced  by  an  X client,  the  font  is  taken  from  the  directory 
lusrllib/Xl  1 /fonts  unless  an  explicit  path  name  to  another  font  directory  is  provided.  You  can 
specify  an  alternative  font  path  using  the  fp  option  to  xset,  as  described  in  Chapter  11,  Setup 
Clients. 

♦This  is  an  acronym  for  “what  you  see  is  what  you  get”  and  describes  a type  of  text  editor  or  word  processor  that  dis- 
plays the  page  exactly  as  it  would  appear  in  print.  MacWrite®  is  a Wysiwyg  program. 
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Figure  5-11.  Default  font,  fixed 


When  a font  is  referenced  by  an  X client,  the  font  is  taken  from  the  directory 
lusrlliblXll /fonts  unless  an  explicit  path  name  to  another  font  directory  is  provided.  You  can 
specify  an  alternative  font  path  using  the  f p option  to  xset,  as  described  in  Chapter  1 1,  Setup 
Clients. 
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Graphics  Utilities 

This  chapter  describes  how  to  use  the  major  graphics  clients  included  with  X, 

notably  the  bitmap  editor. 

In  This  Chapter: 

Creating  Icons  and  Other  Bitmaps  109 

Bitmap  Editing  Commands Ill 
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Bitmap  Command  Boxes  112 
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Quitting  xmag  123 
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The  standard  release  of  X includes  four  utilities  to  help  you  create  bitmap  images:  bitmap, 
bmtoa,  atobm,  and  xmag.  The  most  powerful  and  useful  of  these  clients  is  bitmap,  a program 
that  lets  you  create  and  edit  bitmap  files.  The  following  sections  include  detailed  instructions 
for  using  the  bitmap  client. 

The  bmtoa  and  atobm  clients  are  programs  that  convert  bitmaps  to  arrays  (of  ASCII  charac- 
ters) and  arrays  to  bitmaps.  They  are  used  to  facilitate  printing  and  file  manipulation  and  can 
help  you  convert  a font  character  to  a bitmap. 

In  a sense,  the  xmag  client  is  a desk  accessory  for  graphics  programs.  This  client  is  used  to 
magnify  a portion  of  the  screen,  assisting  you  in  creating  images  with  a graphics  editor,  such 
as  bitmap. 


Creating  Icons  and  Other  Bitmaps 

The  bitmap  program  allows  you  to  create  and  edit  small  bitmaps.  A bitmap  is  a grid  of  pix- 
els, or  picture  elements,  each  of  which  is  white,  black,  or,  in  the  case  of  color  displays,  a 
color.  You  can  use  bitmap  to  create  backgrounds,  icons,  and  pointers. 

At  this  point  in  X Window  System  development,  bitmap  is  primarily  a programming  tool  for 
application  developers.  However,  several  applications  allow  you  to  design  your  own  icon  or 
background  pattern  with  bitmap,  save  it  in  a bitmap  file,  and  specify  that  filename  on  the 
command  line.*  For  example,  xsetroot  (described  in  Chapter  11,  Setup  Clients ) allows  you 
to  specify  a bitmap  that  will  be  used  as  the  background  pattern  for  the  root  window. 

To  invoke  bitmap,  type: 

% bitmap  filename  & 

An  upper-left  comer  cursor  appears  on  the  screen  for  you  to  interactively  place  the  bitmap 
window,  shown  in  Figure  6-1. 


* There  are  many  bitmaps  included  in  the  X distribution.  These  can  be  found  in  the  directory  lusr/ir xcludelXl  1 /bit- 
maps. Samples  are  shown  in  Appendix  G,  Standard  Bitmaps. 
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Figure  6-1.  Bitmap  window 


The  window  that  bitmap  creates  has  three  sections: 

1.  The  largest  section  is  the  checkerboard  grid,  which  is  a magnified  version  of  the  bitmap 
you  arc  editing.  The  default-size  grid  is  16x16.  If  this  grid  isn’t  large  enough  for  com- 
fortable editing,  resize  the  window.  Each  square  on  the  grid  will  be  enlarged  proportion- 
ally. 

2.  On  the  right-hand  side  of  the  window  is  a list  of  commands  in  command  boxes  that  you 
can  invoke  with  any  mouse  button. 

3.  Beneath  the  commands  is  an  actual-size  picture  of  the  bitmap  you  are  editing;  below  this 
is  an  inverted  version  of  the  same  bitmap.  Each  time  the  grid  changes,  the  same  change 
occurs  in  the  actual-size  bitmap  and  its  inverse. 

If  you  want  to  edit  in  a grid  of  different  proportions  than  the  default-size  16x16  grid,  you  can 
specify  wiDTHxHEiGHT  on  the  command  line,  after  filename.  For  example,  to  create  a 
grid  double  the  size  of  the  default,  enter: 

% bitmap  filename  32x32  & 

Figure  6-2  shows  a 40x40  grid  with  a bitmap  we  created  of  Gumby©.  We  think  it  makes  a 
fun  root  window  pattern.  (See  the  discussion  of  xsetroot  in  Chapter  11,  Setup  Clients , for 
instructions  on  specifying  a bitmap  as  your  root  window  pattern.) 
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Figure  6-2.  Gumby  bitmap 


Figure  6-2  shows  our  own  rendition  of  Gumby,  created  using  various  bitmap  editing  com- 
mands. The  standard  cursor  font  also  contains  a Gumby  character.  (You  can  specify  the 
Gumby  cursor  as  the  xterm  window  pointer,  as  described  in  Chapter  9,  Setting  Resources,  or 
as  the  root  window  pointer  using  the  xsetroot  client,  as  described  in  Chapter  11,  Setup 
Clients.)  Later  in  this  chapter,  we’ll  show  you  how  to  convert  the  Gumby  character  of  the 
cursor  font  to  a bitmap  file,  using  the  atobm  client. 


Bitmap  Editing  Commands 

You  can  create  and  edit  a bitmap  using  a combination  of  pointer  commands  and  commands 
that  appear  in  boxes  on  the  right-hand  side  of  the  window.  The  pointer  commands  work  on 
one  square  of  the  grid  at  a time,  while  the  command  boxes  can  work  on  the  entire  grid  or  a 
specified  area. 
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Pointer  Commands 


When  the  pointer  is  in  the  checkerboard  grid,  each  mouse  button  has  a different  effect  upon 
the  single  square  under  the  pointer.  You  can  hold  down  a mouse  button  and  drag  the  pointer 
to  effect  several  squares  in  a row. 

left  button  Changes  a grid  square  to  the  foreground  color  and  sets  the  corresponding 

bitmap  bit  to  1.  (On  a monochrome  display,  background  color  means 
white  and  foreground  color  means  black.) 

middle  button  Inverts  a grid  square,  changing  its  color  and  inverting  its  bitmap  bit. 

right  button  Changes  a grid  square  to  the  background  color  and  sets  the  corresponding 
bitmap  bit  to  0. 

Bitmap  Command  Boxes 

To  invoke  any  bitmap  command,  move  the  pointer  to  the  appropriate  command  box  and  click 
any  button,  bitmap  does  not  have  an  Undo  command.  Once  you  have  made  a change,  you 
cannot  retrieve  the  original. 

Acting  on  the  Entire  Grid:  Clear  All,  Set  All,  Invert  All 

To  Clear  All,  Set  All,  or  Invert  All,  click  on  the  appropriate  command  box. 

Clear  All  Changes  all  the  grid  squares  to  the  background  color  and  sets  all  bit- 

map bits  to  0. 


Figure  6-3.  Clearing  all 
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Set  All 


Changes  all  the  grid  squares  to  the  foreground  color  and  sets  all  bit- 
map bits  to  1. 


Figure  6-4.  Setting  all 

Invert  All  Inverts  all  the  grid  squares  and  bitmap  bits,  as  if  you  had  pressed  the 

middle  button  over  each  square. 


I Clear  All  ~~| 

I Set  All  ~1 


Invert  All 


I Clear  Area 

| Set  Area 

| Invert  Area 

| Copy  Area 

1 Move  Area 
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Figure  6-5.  Inverting  all 
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Acting  on  an  Area:  Clear  Area,  Set  Area,  Invert  Area 


Clear  Area 

Clears  a rectangular  area  of  the  grid,  i.e.,  changes  it  to  the  back- 
ground color,  and  sets  the  corresponding  bitmap  bits  to  0. 

Set  Area 

Changes  a rectangular  area  of  the  grid  to  the  foreground  color  and 
sets  the  corresponding  bitmap  bits  to  1 . 

Invert  Area 

Changes  a rectangular  area  of  the  grid  from  the  background  color  to 
the  foreground  color  or  the  foreground  color  to  the  background 
color. 

Figure  6-6.  Selecting  an  area  to  clear,  set,  or  invert 


The  procedure  to  act  on  an  area  is  as  follows: 

1.  Click  the  pointer  over  the  command  (Clear  Area,  Set  Area,  or  Invert  Area).  The  pointer 
turns  into  an  upper-left  comer. 

2.  Move  the  pointer  over  the  upper-left  comer  of  the  area  you  want  to  clear,  set,  or  invert. 
Press  and  hold  any  button.  The  pointer  changes  to  a lower-right  comer. 

3.  Move  the  pointer  to  the  lower-right  comer  of  the  area  you  want  to  act  on.  X’s  cover  the 
rectangular  area  as  you  move  the  pointer.  Release  the  button. 

If  the  pointer  has  changed  to  a lower-right  comer  and  you  wish  to  abort  the  command 
without  inverting  an  area,  either  click  another  button,  move  the  pointer  outside  the  grid, 
or  move  the  pointer  above  or  to  the  left  of  the  upper-left  comer. 
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Copy  Area,  Move  Area,  Overlay  Area 


Copy  Area  Copies  a rectangular  area  from  one  part  of  the  grid  to  another. 

Move  Area  Moves  a rectangular  area  from  one  part  of  the  grid  to  another. 


Overlay  Area  Lays  a rectangular  area  from  one  part  of  the  grid  over  a rectangular 

area  in  another  part  of  the  grid.  Overlay  is  not  a pixel-for-pixel 
replacement,  but  those  pixels  that  are  clear  (bitmap  bits  set  to  0) 
allow  those  pixels  that  are  set  (bitmap  bits  set  to  1)  to  show  through 
the  overlay. 


Figure  6-7.  Selecting  an  area  to  copy,  move,  or  overlay 


The  procedure  to  Copy  Area,  Move  Area,  or  Overlay  Area  is  as  follows: 

1.  Click  the  pointer  over  the  command  (Copy  Area,  Move  Area,  or  Overlay  Area).  The 
pointer  turns  into  an  upper-left  comer. 

2.  Move  the  pointer  over  the  upper-left  comer  of  the  area  you  want  to  copy,  move,  or  over- 
lay. Press  and  hold  any  button.  The  pointer  changes  to  a lower-right  comer. 

3.  Move  the  pointer  to  the  lower-right  comer  of  the  area  you  want  to  act  on.  X’s  cover  the 
rectangular  area  as  you  move  the  pointer.  Release  the  button.  The  pointer  changes  to  an 
upper-left  comer. 
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4.  Move  the  pointer  to  the  desired  location  and  click  any  button. 

OR: 

Press  and  hold  any  button  to  see  the  outline  of  the  destination  rectangle,  move  the  pointer 
to  the  desired  location,  then  release  the  button. 

5.  To  cancel  an  overlay,  copy,  or  move  command,  move  the  pointer  outside  the  grid  and 
release  the  button. 

Drawing:  Line,  Circle,  Filled  Circle 

When  you  use  a drawing  command,  the  drawing  is  always  done  in  the  foreground  color. 

Line  Draws  a line  between  any  two  points  you  select. 

Circle  Draws  a circle.  You  specify  the  center  and  the  radius. 

Filled  Circle  Draws  a filled  circle.  You  specify  the  center  and  the  radius. 
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Filled  Circle  | 


Figure  6-8.  Selecting  center  and  radius  of  circle 


To  draw  a line  or  circle: 

1.  Click  the  pointer  over  the  command  Line,  Circle,  or  Filled  Circle.  The  pointer  changes  to 
the  dot  cursor  shape  (•). 

2.  Move  the  pointer  to  the  first  point  of  the  line  or  to  the  center  of  the  circle.  Click  any  but- 
ton. An  X fills  the  square  which  is  the  starting  point  of  the  line  or  center  of  the  circle. 

3.  Move  the  pointer  to  the  end  point  of  the  line  or  to  the  outside  circumference  of  the  circle. 
Click  any  button.  The  graphic  is  drawn. 
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Filling  In  a Shape:  Flood  Fill 


Flood  Fill  Fills  all  clear  squares  in  a closed  shape. 

To  fill  a shape: 

1.  Click  the  pointer  over  the  command  Flood  Fill.  The  pointer  changes  to  the  dot  cursor 
shape  (•)• 

2.  Move  the  pointer  into  the  shape  you  want  to  fill. 

3.  Click  on  any  clear  square  inside  the  closed  shape  and  all  clear  squares  are  filled  out  to  the 
shape’s  border.  If  the  shape  is  not  closed,  the  entire  grid  will  be  filled. 


Hot  Spots:  Set  Hot  Spot,  Clear  Hot  Spot 

Set  Hot  Spot  Designates  a point  on  the  bitmap  as  the  hot  spot.  If  a program  is 

using  your  bitmap  as  a pointer,  the  hot  spot  indicates  which  point  on 
the  bitmap  will  track  the  actual  location  of  the  pointer.  For  instance, 
if  your  pointer  is  an  arrow,  the  hot  spot  should  be  the  tip  of  the 
arrow;  if  your  pointer  is  a cross,  the  hot  spot  should  be  that  point  at 
which  the  perpendicular  lines  intersect. 

Clear  Hot  Spot  Removes  a hot  spot  defined  on  this  bitmap. 

To  set  or  clear  a hot  spot: 

1.  Click  the  pointer  over  Set  Hot  Spot  or  Clear  Hot  Spot. 

2.  Move  the  pointer  to  the  location  of  the  hot  spot.  Click  any  button.  When  a hot  spot  is 
active  a diamond  (0)  appears  in  the  square. 


Saving  and  Quitting:  Write  Output,  Quit 

Write  Output  Writes  the  current  bitmap  value  to  the  file  specified  in  the  command 

line.  If  the  file  already  exists,  the  original  file  is  first  renamed  to 
filename'. 

If  either  the  renaming  or  the  writing  causes  an  error  (e.g.,  permission 
denied),  a dialog  box  appears,  asking  if  you  want  to  write  the  file 
/tmp/filename  instead.  If  you  click  Yes,  all  future  Write  Output  com- 
mands in  the  current  bitmap  editing  session  write  to  /tmp/filename. 
See  the  bitmap  reference  page  in  Part  Three  of  this  guide  for  infor- 
mation on  the  format  of  the  output  file. 
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Quit 


Terminates  bitmap.  If  you  have  edited  the  bitmap  and  have  not 
invoked  Write  Output,  or  you  have  edited  it  since  the  last  time  you 
invoked  Write  Output,  a dialog  box  appears,  asking  if  you  want  to 
save  changes  before  quitting.  Yes  does  a Write  Output  before  ter- 
minating; No  just  terminates,  losing  the  edits;  Cancel  means  you 
decided  not  to  terminate  after  all. 

You  can  also  terminate  bitmap  by  typing  Control-C  or  q anywhere 
in  the  window.  If  you  have  edited  the  bitmap  and  have  not  invoked 
Write  Output,  a dialog  window  appears,  asking  if  you  want  to  save 
changes  before  quitting. 


Figure  6-9.  Bitmap  window  with  quit  dialog  box 
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Creating  a Bitmap  from  a Cursor 


The  atobm  and  bmtoa  clients  allow  you  to  convert  arrays  (of  ASCII  characters)  to  bitmap 
files  and  to  convert  bit/wap  files  to  arrays.  These  clients  are  commonly  used  to  facilitate 
printing:  a bitmap  file  that  is  converted  to  ASCII  text  can  be  printed  more  readily  and  can 
also  be  included  in  standard  ASCII  text  files.  Once  converted  to  ASCII,  bitmap  files  can  also 
be  more  quickly  copied  or  mailed  to  other  directories  or  systems,  where  they  can  be  used  in 
ASCII  format  or  converted  back  to  bitmap  format. 

Among  their  uses,  the  bmtoa  and  atobm  utilities  make  it  possible  to  convert  a character  from 
a font,  such  as  the  cursor  font,  to  the  bitmap  file  format.  Once  converted,  the  file  can  be 
edited  using  the  bitmap  client,  and  used  as  you  would  any  other  bitmap  file:  specified  as  the 
root  window  pattern  (with  xsetroot),  etc. 

When  a bitmap  file  is  converted  to  ASCII  text,  it  is  in  the  form  of  an  array  consisting  of  two 
types  of  characters.  (An  array  is  a number  of  elements  arranged  in  rows  and  columns;  it  is 
sometimes  called  a matrix.)  One  character  represents  set  or  filled  squares  of  the  bitmap  (bit- 
map bit  1)  and  the  other  character  represents  empty  squares  (bitmap  bit  0).  By  default,  the 
number  sign  character  (#)  represents  filled  squares  and  the  hyphen  (-)  represents  empty 
squares.  Figure  6-10  shows  the  British  pound  sign  character  of  the  9x15  font  (in  the  misc 
directory)  as  an  array  of  these  ASCII  symbols. 


###- 

--# 

#####  — 

--# 

-####  — 
#-#--## 
-# 


Figure  6-10.  ASCII  array  representing  the  pound  sign 

As  you  can  see,  the  array  is  a perfect  rectangle.  In  a sense,  the  array  is  very  similar  to  the  bit- 
map grid.  (You  can  edit  or  create  the  array  using  an  ASCII  text  editor,  so  long  as  you  use  the 
standard  two  characters  and  keep  the  array  rectangular.) 

To  convert  the  Gumby  character  of  the  cursor  font  to  a bitmap,  the  first  thing  you  must  do  is 
display  the  cursor  font  as  ASCII  text.  This  can  be  done  with  the  showsnf  client,  which  allows 
you  to  display  the  contents  of  a font  file  (with  a .snf  extension).  The  -g  option  specifies  that 
arrays  of  all  the  characters  in  the  font  be  displayed  as  well. 

To  display  the  cursor  font  with  each  character  represented  as  an  array,  use  showsnf,  with  the 
font  filename  as  an  argument,  and  redirect  output  to  a file  called  / imp! cursor. array: 

% showsnf  -g  /usr/lib/Xll/fonts/misc/cursor . snf  > /tmp/cursor . array 
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The  cursor.array  file  contains  information  about  the  font  and  an  array  for  each  character. 
Using  your  ASCII  text  editing  program,  edit  the  file,  writing  the  Gumby  array  to  another  file 
called  I tmpl gumby. array.  The  Gumby  array  is  pictured  in  Figure  6-11. 


—###### 

# # 

##— # # 

###-#-#-#-# 

##  — # # 

##-#-###-# 

##### ####  — 

— ### ###### 

# #— ### 

# #— ### 

#--#—#-#### 

#—#  — #—### 

#— #— # 

# #-— # 

— # # # 

— # ####-##### 


Figure  6-11.  Amp/gumby.  array 

You  can  then  use  the  atobm  client  to  convert  this  array  to  a bitmap.  Use  the  gumby. array  file 
as  an  argument  and  redirect  the  output  to  a bitmap  file: 

% atobm  /tmp/gumby . array  > /tmp/gumby . bitmap 

Figure  6-12  shows  the  Gumby  bitmap.  As  you  can  see  from  the  bitmap,  the  Gumby  character 
of  the  cursor  font  is  considerably  smaller  than  the  Gumby  we  created  (Figure  6-2)  with  bit- 
map. 

If  you  want,  you  can  then  edit  the  gumby. bitmap  file  using  the  bitmap  client. 

If  you  specify  the  bitmap  as  the  root  window  pattern,  you’ll  notice  that  there  is  virtually  no 
space  between  the  Gumby  figures.  This  is  because  the  array  file  had  no  extra  hyphens  (repre- 
senting empty  bitmap  squares)  padding  it.  If  you  want,  you  can  add  some  hyphens  to  the 
gumby.array  file  (keeping  the  image  symmetrical)  and  then  use  atobm  to  create  a more  pad- 
ded version  of  the  bitmap.  Figure  6-13  shows  the  gumby.array  file  after  being  padded  with 
hyphens. 

See  the  bitmap  reference  page  in  Part  Three  of  this  guide  for  more  information  on  the  atobm 
and  bmtoa  conversion  clients. 
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Figure  6-12.  Bitmap  of  the  Gumby  cursor 
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Figure  6- 1 3.  gumby.  array  padded  by  hyphens 
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Magnifying  Portions  of  the  Screen:  xmag 


The  xmag  client  enables  you  to  magnify  a portion  of  the  screen.  The  close-up  look  xmag 
affords  can  assist  you  in  creating  and  editing  bitmaps  and  other  graphic  images. 

xmag  is  primarily  a tool  for  application  developers  using  sophisticated  graphics  programs. 
But  you  could  also  use  xmag  in  concert  with  the  bitmap  client.  For  instance,  say  you’re  run- 
ning a program  that  creates  a special  image  on  the  root  window  and  you’d  like  to  create  a bit- 
map file  of  a part  of  that  image.  You  can  display  a magnification  of  the  image  you  want  with 
xmag , and  try  to  recreate  the  image  by  editing  in  an  open  bitmap  window. 

If  you  invoke  xmag  without  options,  you  can  interactively  choose  the  area  to  be  magnified 
(the  source  area)  and  position  the  magnified  image  on  your  screen.  At  the  command  line, 
type: 

% xmag  & 

The  pointer  changes  to  a small  cross  (the  crosshair  cursor)  in  the  center  of  a small,  hollow 
square  with  a wavering  border.  (By  default,  the  square  is  64  pixels  on  each  side.)  Move  the 
crosshair  cursor,  placing  the  square  over  the  area  you  want  to  magnify,  and  click  the  first 
mouse  button. 

The  crosshair  changes  to  an  upper-left  comer  cursor,  and  the  hollow  square  becomes 
enlarged  to  the  size  of  the  magnified  image.  (By  default,  the  image  is  magnified  five  times.) 
Move  the  upper-left  comer  cursor,  positioning  the  square  where  you  want  the  magnified 
image.  Again  click  the  first  mouse  button  and  the  xmag  window  containing  the  magnified 
bitmap  image  is  displayed,  as  shown  in  Figure  6-14. 

If  you  are  using  a window  manager  that  provides  titlebars,  such  as  twm,  the  title  string  “Mag- 
nifying Glass”  will  be  displayed  in  the  xmag  window  titlebar.  This  is  the  default  title  string 
of  the  application.* 

The  default-size  xmag  window  shows  an  area  64  pixels  square,  magnified  five  times.  This 
magnification  enables  you  to  see  the  individual  pixels,  which  are  represented  by  squares  of 
the  same  color  as  the  corresponding  pixels  in  the  source  image. 

Rather  than  use  the  default  source  area  and  magnification,  you  can  specify  other  values  on 
the  command  line.  See  the  xmag  reference  page  in  Part  Three  of  this  guide  for  a complete 
list  of  options. 


‘Applications  written  using  the  X Toolkit  allow  you  to  change  the  title  string.  See  the  section  “Title  and  Name”  in 
Chapter  8,  Command  Line  Options,  for  details.  The  xmag  client  was  not  written  using  the  X Toolkit  and  provides  no 
method  for  changing  the  title  string. 


122 


X Window  System  User’s  Guide 


Figure  6-14.  xmag  window  displaying  magnified  screen  area 

Quitting  xmag 

To  exit  the  program,  type  q,  Q,  or  Control-C  in  the  xmag  window. 

What  xmag  Shows  You 

xmag  enables  you  to  determine  the  x and  y coordinates,  bitmap  bit  setting,  and  RGB  color 
value  of  every  pixel  in  the  xmag  window.  (Sec  Chapter  8,  Command  Line  Options,  for  a dis- 
cussion of  the  RGB  color  model.)  If  you  move  the  pointer  into  the  xmag  window,  the  cursor 
becomes  an  arrow.  Point  the  arrow  at  one  of  the  magnified  pixels  and  press  and  hold  down 
the  first  mouse  button.  Across  the  top  edge  of  the  window,  a banner  displays  information 
about  the  pixel,  as  shown  in  Figure  6-15. 
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Figure  6-15.  Displaying  pixel  statistics  with  xmag 

The  banner  displays  the  following  information  about  the  specified  pixel: 

• The  x and  y coordinates  relative  to  the  window.  The  default  xmag  window  is,  in  effect,  a 
grid  of  64  squares  on  each  side.  Therefore,  each  pixel  has  x,y  coordinates  between  0,0 
and  63,63. 

• The  bitmap  bit  setting.  This  is  either  0,  if  the  pixel  is  in  the  background  color,  or  1,  if  the 
pixel  is  in  the  foreground  color. 

• The  RGB  value.  This  is  a 16-bit  value.  The  RGB  specification  is  in  three  parts  (of  four 
hexadecimal  digits  each),  corresponding  to  the  three  primaries  in  the  RGB  color  model. 

If  you  are  trying  to  create  a graphic  image  on  a grid  (such  as  the  bitmap  client  provides),  the 
x and  y coordinates  of  each  pixel  can  be  especially  useful.  Also,  the  16-bit  RGB  value  speci- 
fies the  color  of  each  pixel  with  incredible  precision.  Depending  on  the  number  of  colors 
available  on  your  display,  you  can  learn  to  use  RGB  values  to  specify  an  enormous  range  of 
colors. 

xmag  provides  these  pixel  statistics  dynamically.  If  you  continue  to  hold  down  the  first 
mouse  button  and  drag  the  pointer  across  the  window,  the  banner  will  display  values  for  each 
pixel  as  the  pointer  indicates  it. 

Note  that  if  you  select  a pixel  near  the  top  edge  of  the  window,  the  banner  will  appear  across 
the  bottom  edge.  Otherwise,  the  banner  would  obscure  the  pixel  you  are  pointing  at. 
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Dynamically  Choosing  a Different  Source  Area 


If  you  want  to  magnify  another  portion  of  the  screen  using  the  same  source  area  size  and 
magnification,  you  do  not  have  to  start  xmag  again.  Simply  move  the  pointer  into  the  xmag 
window  and  click  the  second  or  third  mouse  button,  or  press  the  space  bar.  The  magnified 
image  disappears  and  again  the  cursor  becomes  a crosshair  surrounded  by  a hollow  square. 
Move  the  crosshair  cursor,  placing  the  square  over  the  new  source  area  you  want  to  magnify, 
and  click  any  mouse  button.  The  magnified  image  is  immediately  displayed  in  the  location 
you  placed  the  first  image. 

You  can  select  any  number  of  source  areas  during  a single  xmag  session. 
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Other  Clients 


This  chapter  gives  an  overview  of  other  clients  available  with  X,  including 
window  and  display  information  clients,  printing  utilities,  the  xkill  program, 
and  several  “ desk  accessories.  ” 
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In  addition  to  twm  and  xterm,  the  MIT  distribution  includes  many  other  clients.  As  X 
becomes  more  widely  available,  there  will  doubtless  be  many  applications  available  from 
third  parties,  just  as  there  are  in  the  PC  world. 

The  clients  discussed  in  this  chapter  are  grouped  according  to  basic  functionality,  as  follows: 

• Desk  accessories:  xclock,  o clock,  xcalc,xbiff,xload,  and  xman. 

• Printing  utilities:  xwd,  xpr,  and  xdpr. 

• Program  to  remove  a client  window:  xkill. 

• Window  and  display  information  programs:  xwininfo,  xlswins,  xlsclients,  and  xdpyinfo. 

• Alternative  window  managers  and  other  user-contributed  clients. 

In  addition,  we’ve  included  a brief  discussion  of  X Toolkit  applications. 

Most  sections  in  this  chapter  are  intended  to  acquaint  you  with  the  major  features  of  some  of 
the  available  clients.  Additional  detailed  information  is  provided  on  the  reference  pages  for 
each  client  in  Part  Three  of  this  guide. 


Desk  Accessories 


The  clients  xclock,  oclock,  xcalc,  xload,  xbiff,  and  xman  can  be  thought  of  as  desk  acces- 
sories. (Desk  accessories  is  a term  we’ve  borrowed  from  the  Macintosh  environment,  mean- 
ing small  applications  available — and  useful — at  any  time.) 

You  can  start  these  clients  from  the  command  line  in  any  xterm  window,  or,  if  you  like,  you 
can  add  them  to  a Pvm  menu  (see  Chapter  10,  Customizing  the  twm  Window  Manager). 
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Clock  Programs:  xclock  and  oclock 


The  standard  release  of  X includes  two  clients  that  display  the  time:  xclock  and  oclock.  The 
oclock  client  has  been  added  to  the  standard  distribution  of  X in  Release  4. 

xclock  continuously  displays  the  time,  either  in  analog  or  digital  form,  in  a standard  window. 
The  analog  xclock  shows  a round  12-hour  clock  face,  with  tick  marks  representing  the  min- 
utes. The  digital  xclock  shows  the  24-hour  time  (14:30  would  be  2:30  PM)  as  well  as  the  day, 
month,  and  year.  You  can  run  more  than  one  clock  at  a time.  The  analog  clock  is  the  default. 
Figure  7-1  shows  two  xclock  applications  being  run  (an  analog  clock  above  a digital  clock). 


Wed  Feb  28  13:25:13  1990 


Figure  7-1.  Two  xclock  displays:  analog  clock  above  digital  clock 


Usually  when  you  invoke  xclock  you  will  leave  the  clock  running.  However,  if  you  experi- 
ment with  xclock  to  test  size,  location,  or  color,  you  will  notice  that  there  is  no  obvious  way 
to  delete  an  unwanted  clock.  (Moving  the  cursor  to  the  clock  and  pressing  Control-C,  Con- 
trol-D,  q,  or  Q doesn’t  work  with  xclock .)  Actually,  if  you  are  running  Release  2 or  3 of  X, 
the  only  way  to  kill  the  xclock  process  is  as  follows.  First,  display  the  current  X processes 
with  the  command: 

% pa  -aux  | grop  xclock 

For  System  V,  use  the  command: 

% ps  -•  | gr«p  xclock 

and  then  kill  the  process  number  for  the  clock  as  described  in  Chapter  2,  Getting  Started. 

If  you  are  running  Release  4 of  X,  and  thus  are  using  the  twm  window  manager,  you  can 
remove  an  xclock  by  using  the  Delete  command  of  the  Twm  menu.  (See  Chapter  3,  Using  the 
twm  Window  Manager , for  more  details.) 

The  oclock  client  (available  as  of  Release  4)  displays  the  time  in  analog  form,  on  a round 
12-hour  clock  face  without  tick  marks.  The  only  features  of  an  oclock  display  are  the  round 
clock  outline,  hour  and  minute  hands,  and  the  “jewel”  marking  12  o’clock. 
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~C-  ~~  7-2.  ooooc  c sr  tay 


Though  it  is  somewhat  more  difacuh  to  read  the  precise  tune  on  the  sample  ,v.V.t  dispiav 
the  oclock  is  perhaps  a little  more  aesthete  than  the  analog  r.A  t.  If  >ou  trv  to  resize  the 
oclock,  >ou  11  discover  that  it  s rossi  r\e  to  "stretch  it  ir.to  various  oblonc  she  tvs 


(3 


Figure  7-3.  Oblong  oclock  displays 


Though  the  default  colors  for  oclock  are  black  and  white,  it  was  designed  to  be  run  in  color. 
The  minute  hand,  hour  hand,  jewel,  clock  border,  and  background  can  all  be  set  to  a color, 
using  either  command  line  options  (as  described  in  Chapter  S.  Command  Line  Options)  or  bv 
specifying  client  resources  (as  described  in  Chapter  9,  Setting  Resources).  See  the  oclock 
reference  page  in  Part  Three  of  this  guide  for  the  necessary  command  line  options  and  color 
suggestions. 

As  is  the  case  with  xclock,  there  is  no  simple  way  to  remove  an  oclock  window.  Use  the 
UNIX  commands  ps,  grep , and  kill  in  the  sequence  described  above. 

The  time  displayed  by  both  xclock  and  oclock  is  the  system  time  set  and  displayed  with  the 
UNIX  date{  1)  command. 
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A Scientific  Calculator:  xcalc 


xcalc  is  a scientific  calculator  that  can  emulate  a TI-30  or  an  HP- IOC.  Once  you  place  the 
pointer  within  the  xcalc  window,  the  calculator  can  be  operated  in  two  ways:  with  the 
pointer,  by  clicking  the  first  pointer  button  on  the  buttons  in  the  calculator  window,  or  with 
the  keyboard,  by  typing  the  same  numbers  and  symbols  that  are  displayed  in  the  calculator 
window.  When  using  the  first  method,  notice  that  the  pointer  appears  as  a small  hand,  ena- 
bling you  to  “press”  the  buttons.  Figure  7-4  shows  xcalc  on  the  screen. 


Figure  7-4.  The  default  xcalc  ( TI-30  mode)  on  the  screen 


This  is  the  version  of  the  calculator  provided  with  Release  4 of  X.  As  you  can  see,  it  features 
oval  buttons.  If  you  are  running  an  earlier  release,  the  calculator  will  have  rectangular  but- 
tons and  may  also  have  darker  background  coloring.  These  differences  do  not  affect  func- 
tionality. How'ever,  the  Release  3 and  Release  4 versions  of  xcalc  do  work  somewhat  differ- 
ently. We’ve  described  some  of  those  differences  below.  For  additional  information,  see  the 
xcalc  reference  page  in  Part  Three  of  this  guide. 

The  long  horizontal  window  along  the  top  of  the  calculator  is  the  display  in  w'hich  the  values 
are  punched  on  the  calculator  and  their  results  are  displayed.  You  can  enter  values  either  by 
clicking  on  the  calculator  keys  with  the  pointer,  or  by  pressing  equivalent  keys  on  the  key- 
board. Most  of  the  calculator  keys  have  keyboard  equivalents.  The  non-obvious  equivalents 
are  described  on  the  xcalc  reference  page  in  Part  Three. 
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By  default,  xcalc  works  like  a Texas  Instruments  77-50  calculator.  To  interactively  place 
xcalc  in  this  mode,  type: 

% xcalc  & 

You  can  also  operate  the  calculator  in  Reverse  Polish  Notation  (like  a Hewlett-Packard 
HP-10C  calculator),  by  typing: 

% xcalc  -rpn  & 

In  Reverse  Polish  Notation  the  operands  are  entered  first,  then  the  operator.  For  example,  5 

• 4 = would  be  entered  as  5 Enter  4 *.  This  entry  sequence  is  designed  to  minimize 
keystrokes  for  complex  calculations. 

As  of  Release  4,  xcalc  allows  you  to  select  the  number  in  the  calculator  display  using  the  first 
(left)  pointer  button  and  paste  it  in  another  window  using  the  second  (middle)  button.  See 
Chapter  4,  The  xterm  Terminal  Emulator,  for  information  about  copying  and  pasting  text 
selections. 

The  Release  4 xcalc  can  also  be  resized.  In  prior  releases,  this  was  not  possible. 

Also  as  of  Release  4,  xcalc  no  longer  emulates  a slide  rule.* 

For  more  information  on  the  function  of  each  of  the  calculator  keys,  see  the  xcalc  reference 
page  in  Part  Three  of  this  guide. 

Terminating  the  calculator 

Terminate  the  calculator  by  either: 

• Clicking  the  third  pointer  button  (usually  the  rightmost  button)  on  the  TI  calculator’s  AC 
key  or  the  HP  calculator’s  ON  key,  or: 

• Positioning  the  pointer  on  the  calculator  and  typing  q,  Q,  or  Control-C. 


Mail  Notification  Client:  xbiff 


xbijf  is  a simple  program  that  notifies  you  when  you  have  mail.  It  puts  up  a window  showing 
a picture  of  a mailbox.  When  you  receive  new  mail,  a beep  is  emitted  from  the  keyboard,  the 
flag  on  the  mailbox  goes  up,  and  the  image  changes  to  reverse  video.  Figure  7-5  shows  the 
xbiff  mailbox  before  and  after  mail  is  received. 

After  you  read  your  mail,  the  image  changes  back  to  its  original  state.  Or  you  can  click  on 
the  full  mailbox  icon  with  any  pointer  button  to  change  it  back  to  empty.  (Regardless  of  the 
number  of  mail  messages  when  you  do  this,  xbiff  remembers  the  current  size  of  your  mail  file 
to  be  the  empty  size.) 

♦If  you  are  running  an  earlier  release  of  X,  you  can  operate  xcalc  as  a slide  rule  by  using  the  -analog  option.  You 
drag  the  slide  using  the  first  pointer  button.  Be  aware  that  the  slide  rule  mode  doesn’t  work  very  well.  To  terminate 
the  slide  rule,  use  kill{\),  as  described  above  for  xclock.  The  slide  rule  emulation  has  been  eliminated  in  Release  4. 
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Figure  7-5.  xbiff  before  and  after  mail  is  received 


Monitoring  System  Load  Average:  xload 

xload  periodically  polls  the  system  for  the  load  average,  and  graphically  displays  that  load 
using  a simple  histogram.  By  default,  xload  polls  the  system  every  5 seconds.  You  can 
change  this  frequency  with  the  -update  option.  For  example,  if  you  type  the  following 
command  at  an  x term  window: 

% xload  -update  3 & 

you  can  interactively  place  an  xload  window  polling  every  3 seconds. 


your  system 

AiJ 

Figure  7-6.  A sample  xload  window 

If  you  are  using  both  the  local  machine  and  remote  machines,  you  can  display  loads  for  all 
systems  and  do  your  processing  on  the  system  that  is  fastest  at  the  time. 
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Browsing  Reference  Pages:  xman 


The  xman  client  allows  you  to  display  and  browse  through  formatted  versions  of  manual 
pages  (reference  pages).  By  default,  xman  lets  you  look  at  the  standard  UNIX  manpages 
found  in  subdirectories  of  the  directory  lusr/man.  The  standard  version  of  X assumes  there 
are  ten  subdirectories:  manl  through  man8,  corresponding  to  the  eight  sections  of  manpages 
in  the  UNIX  documentation  set;  manl  (man  local)  and  mann  (man  new).  You  can  specify 
other  directories  by  setting  the  MANPATH  system  variable.  (The  individual  directory  names 
should  be  separated  by  colons.) 

This  section  describes  the  version  of  xman  provided  with  Release  4 of  X.  From  a user’s 
viewpoint,  the  general  operation  of  the  client  has  not  changed  much  since  prior  releases,  but 
the  organization  of  menus  and  options  has  changed.  If  you  are  running  Release  3 of  X,  read 
this  section  for  an  idea  of  how  the  client  works  and  then  take  a look  at  the  next  section, 
“Release  3 xman,”  for  a summary  of  the  differences. 

Regardless  of  the  version  of  X,  you  run  xman  by  typing: 

% xman  & 

in  an  xterm  window. 

The  initial  x man  window,  shown  in  Figure  7-7,  is  a small  window  containing  only  a few  com- 
mands. 


Manual  Browser 
C Help  ) ( Quit  ) 
C Manual  Page  ) 


Figure  7-7.  Initial  xman  window 

This  window  is  small  enough  to  be  displayed  for  prolonged  periods  during  which  you  might 
have  need  to  examine  UNIX  manual  pages.  You  select  a command  by  clicking  on  it  with  the 

first  pointer  button. 

The  Manual  Page  command  brings  up  a larger  window  in  which  you  can  display  a formatted 
version  of  any  manual  page  in  the  MANPATH.  By  default,  the  first  page  displayed  contains 
general  help  information  about  xman.  Use  this  information  to  acquaint  yourself  with  the  cli- 
ent’s features.  (The  actual  xman  reference  page  in  Part  Three  of  this  guide  primarily 
describes  how  to  customize  the  client.) 
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Once  you’ve  opened  this  larger  window,  you  can  display  formatted  manual  pages  in  it.* 
Notice  the  horizontal  bar  spanning  the  top  edge  of  the  window.  (If  you’re  running  twm  or  a 
similar  window  manager,  this  bar  appears  beneath  the  titlebar  provided  by  the  window  man- 
ager.) The  bar  is  divided  into  three  parts,  labeled  Options,  Sections,  and  Xman  Help.  The  part 
currently  labeled  Xman  Help  is  merely  informational  and  the  text  displayed  in  it  will  change 
depending  on  the  contents  of  the  window.  The  parts  labeled  Options  and  Sections  are  actu- 
ally handles  to  two  xman  menus. 

If  you  place  the  pointer  on  the  Options  box  and  press  and  hold  down  the  first  button,  a menu 
called  Xman  Options  will  be  displayed  below.  The  menu  is  pictured  in  Figure  7-8. 


Figure  7-8.  Xman  Options  menu 

The  functionality  of  these  options  is  described  in  the  on-line  xman  help  page.  To  select  an 
option,  move  the  pointer  down  the  menu  and  release  the  first  button  on  the  option  you  want. 
The  option  you  will  probably  want  to  use  most  frequently  is  the  first  one,  Display  Directory. 

Display  Directory  lists  the  manpages  in  the  current  manpage  directory  (also  called  a “sec- 
tion”). By  default,  this  is  manl,  the  user  commands.  When  you  list  the  contents  of  manl  in 
this  way,  the  informational  section  of  the  horizontal  bar  reads  Directory  of:  (1)  User  Com- 
mands. You  can  then  display  a formatted  version  of  any  command  reference  page  in  the  list 
by  clicking  on  the  command’s  name  with  the  first  pointer  button.  Figure  7-9  shows  the  for- 
matted reference  page  for  the  UNIX  cd(  1)  command. 


*Selecting  the  Help  command  also  opens  a large  window  in  which  the  same  help  information  is  displayed.  The  Help 
command  is  something  of  a dead  end,  however.  You  cannot  display  any  other  text  in  this  window. 
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Options  Sections 


The  current  manual  page  is:  cd. 


SYNOPSIS 


NAME 


CD(1) 


cd  - change  working  directory 


USER  Commands 


CD(l) 


cd  directory 

DESCRIPTION 

Directory  becomes  the  new  working  directory.  The  process  must 
have  execute  (search)  permission  in  directory. 

Because  a new  process  is  created  to  execute  each  command,  cd 
would  be  ineffective  if  it  were  written  as  a normal  command. 
It  is  a therefore  recognized  and  executed  by  the  shells.  In 
csh(l)  you  may  specify  a list  of  directories  in  which  direc- 
tory is  to  be  sought  as  subdirectory  if  it  is  not  a sub- 
directory of  the  current  directory;  see  the  description  of 
the  cdpath  variable  in  csh(l). 


SEE  ALSO 

csh(l),  sh(i),  pwa(l),  chdir(2) 


To  display  another  manual  page  from  the  same  directory,  display  the  Xman  Options  menu 
again.  Select  Display  Directory,  and  the  directory  listing  is  again  displayed  in  the  window. 
Then  click  on  another  command  name  to  display  its  manual  page  in  the  window.  (If  you 
decide  not  to  display  another  manpage,  you  can  remove  the  directory  listing  and  go  back  to 
the  manpage  previously  displayed  by  using  the  second  Xman  Options  menu  selection,  Display 
Manual  Page.  Display  Directory  and  Display  Manual  Page  are  toggles  of  one  another.) 

To  display  a manual  page  from  another  directory  in  the  MANPATH,  you  must  first  change  to 
that  directory  using  the  second  xman  menu,  Xman  Sections.  You  bring  up  the  menu  by  plac- 
ing the  pointer  in  the  Sections  box  in  the  application’s  titlebar  and  holding  down  the  first  but- 
ton. The  Xman  Sections  menu  lists  the  default  directories  of  UNIX  manual  pages,  as  in 
Figure  7-10. 
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Xman  Sections 

(1)  User  Commands 

(2)  System  Calls 

(3)  Subroutines 

(4)  Devices 

(5)  File  Formats 

(6)  Games 

(7)  Miscellaneous 

(8)  Sys.  Administration 
(I)  Local 

(n)  New 

(o)  Old 


Figure  7-10.  Xman  Sections  menu 

You  can  select  another  directory  of  manpages  from  which  to  choose  with  the  first  pointer  but- 
ton. Once  you  select  a directory,  the  files  in  that  directory  are  listed  in  the  window.  Again, 
you  display  a page  by  clicking  on  its  name  with  the  first  pointer  button. 

You  can  display  more  than  one  “browsing”  window  simultaneously  by  selecting  the  Open 
New  Manpage  option  from  the  Xman  Options  menu.  An  additional  manpage  window  will  be 
opened,  again  starting  with  the  help  information. 

You  can  remove  a browsing  window  by  selecting  the  Remove  This  Manpage  option  from  the 
Xman  Options  menu.  (Prior  to  Release  4,  selecting  this  option  resulted  in  an  error  and  caused 
the  xman  program  to  exit.) 

Selecting  Quit  from  the  Xman  Options  menu  or  from  the  initial  xman  window  causes  the  cli- 
ent to  exit. 

Release  3 xman 

In  the  Release  3 version  of  xman,  the  horizontal  bar  spanning  the  top  of  the  browsing  window 
merely  contains  information  about  the  contents  of  the  window.  It  is  not  divided  and  it  does 
not  contain  obvious  text  handles  to  any  menus. 

Though  it  may  not  be  readily  apparent,  you  can  access  the  Xman  Options  menu  simply  by 
placing  the  pointer  in  the  horizontal  bar.  You  can  then  display  manpages  from  the  default 
directory  by  following  the  steps  outlined  in  the  previous  section.  Xman  Options  is  the  only 
menu  directly  accessible  from  the  horizontal  bar. 

The  Release  3 Xman  Options  menu  differs  slightly  in  options  and  organization  from  the 
Release  4 menu.  The  Release  3 menu  is  pictured  in  Figure  7-11. 
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— 

Xman  Options 

| Change  Section 

1 Display  Directory 

| Display  Manual  Page 

j Help 

| Search 

| Show  Both  Screens 

| Remove  This  Manpage  | 

| Open  New  Manpage 

| Quit 

Figure  7-1 1.  Release  3 Xman  Options  menu 

Again,  you  can  acquaint  yourself  with  the  various  options  by  reading  the  help  information 
displayed  on  the  initial  manual  page.  Most  of  the  options  and  functionality  are  the  same  as 
described  above  for  Release  4. 

The  most  significant  difference  is  the  method  of  changing  directories  within  the  MANPATH. 
As  we’ve  seen  in  the  Release  4 version  of  xman,  this  is  accomplished  through  the  Xman  Sec- 
tions menu,  which  is  accessible  directly  from  the  horizontal  bar.  In  the  Release  3 version,  in 
order  to  change  directories  you  must  first  bring  up  the  Xman  Options  menu.  Then  select  the 
first  option,  Change  Section  (which  has  been  removed  from  the  Release  4 menu).  A sub- 
menu of  Xman  Options,  called  Manual  Sections,  will  be  displayed.  This  sub-menu  is  the  R3 
equivalent  of  the  R4  Xman  Sections  menu. 

Like  Xman  Sections,  the  Manual  Sections  menu  lists  the  default  directories  of  UNIX  manual 
pages.  You  can  select  an  alternate  directory  by  the  method  described  in  the  previous  section. 

The  Release  3 version  of  xman  has  one  serious  limitation.  Selecting  the  option  Remove  This 
Manpage  from  the  Xman  Options  menu  results  in  an  error  and  causes  the  xman  program  to 
exit.  (This  error  has  been  corrected  in  Release  4.) 
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Printing  Utilities:  xwd,  xpr,  xdpr 


xwd  stores  window  images  in  a formatted  window  dump  file.  This  file  can  be  read  by  various 
other  X utilities  for  redisplay,  printing,  editing,  formatting,  archiving,  image  processing,  etc. 

To  create  a window  dump  file,  type: 

% xwd  > file 

The  pointer  will  change  to  a small  crosshair.  Move  the  crosshair  pointer  to  the  desired  win- 
dow and  click  any  button.  The  keyboard  bell  rings  once  when  the  dump  starts  and  twice  in 
rapid  succession  when  the  dump  is  finished. 

To  make  a dump  of  the  entire  root  window  (and  all  windows  on  it),  use  the  -root  option,  as 
in  the  following: 

% xwd  -root  > file 

When  you  select  a single  window,  by  default  xwd  takes  an  image  of  the  window  proper.  As 
of  Release  4,  to  include  a window  manager  frame  or  titlebar,  use  the  -frame  option. 

To  redisplay  a file  created  with  xwd  in  a window  on  the  screen,  use  the  xwud  client,  an 
wndumping  utility.  Specify  the  dump  file  to  display  as  an  argument  to  the  -in  option,  as  in 
the  following: 

% xwud  -in  file 

Then  remove  the  image  be  typing  Control-C  in  the  xterm  from  which  you  started  xwud. 

xpr  takes  as  input  an  X Window  System  dump  file  produced  by  xwd  and  converts  it  to  a 
printer-specific  format  that  can  be  printed  on  the  DEC  LN03  or  LA  100  printer,  a PostScript 
printer  such  as  the  Apple  LaserWriter,  the  IBM  PP3812  page  printer,  and  as  of  Release  4,  the 
HP  LaserJet  (or  other  PCL  printers)  or  the  HP  PaintJet.  By  default,  output  is  formatted  for 
the  DEC  LN03  printer.  Use  the  -device  option  to  format  for  another  printer.  For  example, 
to  format  a window  dump  file  for  a PostScript  printer,  type: 

% xpr  -device  ps  file  > file.ps 

Other  options  allow  you  to  change  the  size,  add  headers  or  footers,  and  so  on.  See  the  xpr 
reference  page  in  Part  Three  of  this  guide  for  details. 

You  can  use  xwd  and  xpr  together,  using  the  standard  UNIX  pipe  mechanism.  For  example: 

% xwd  | xpr  -dovico  ps  | lpr 

The  xdpr  command  rolls  these  three  separate  commands  into  one.  See  the  xdpr  reference 
page  in  Part  Three  of  this  guide  for  details. 

Note  that  when  you  start  piping  together  the  output  of  X clients,  you  run  into  some  ambigui- 
ties. For  example,  if  you  pipe  the  output  of  xwd  to  xpr , and  for  some  reason,  the  xpr  com- 
mand fails,  xwd  will  still  be  there  waiting  for  pointer  input.  The  original  UNIX  pipe  mecha- 
nism doesn’t  have  the  concept  of  data  dependent  on  pointer  input!  The  integration  of  the 
UNIX  model  of  computing  (in  which  standard  input  and  output  are  always  recognized),  and 
the  window  model,  is  not  always  complete,  leading  sometimes  to  unexpected  behavior. 
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As  an  even  more  flagrant  example,  you  can  create  a pipe  between  two  programs  the  first  of 
which  doesn’t  produce  standard  output,  and  the  second  of  which  doesn’t  recognize  standard 
input.  The  shell  doesn  t know  any  better,  and  the  programs  themselves  go  on  their  merry  way 
with  pointer  and  windows. 

However,  it  is  nice  to  know  that  you  can  pipe  together  output  of  programs,  even  when  some 
of  those  programs  may  not  produce  output  until  you  intervene  with  the  pointer. 

Even  without  pipes,  you  should  start  thinking  about  how  these  programs  could  work  together. 
For  example,  the  pictures  of  fonts  in  Appendix  E,  Release  3 and  4 Standard  Fonts,  were 
created  by  these  steps: 

1.  Display  a font  with  xfd.  (See  Chapter  5,  Font  Specification , for  instructions  on  how  to  use 
xfd .) 

2.  Resize  the  window  to  improve  readability,  using  the  twm  resize  box  on  the  titlebar. 

3.  Create  a window  dump  file  with  the  command  xwd  > file. 

4.  Create  a PostScript  file  from  the  dump  with  the  command: 

xpr  -device  ps  file>file.ps 

5.  Print  the  PostScript  file  on  an  Apple  LaserWriter  with  the  standard  print  command  lpr(  1). 

Even  though  the  UNIX  shell  will  accept  a pipe  between  xfd,  xwd , and  xpr,  what  actually  hap- 
pens is  that  xwd  starts  up  faster  than  xfd,  and  is  ready  to  dump  a window  before  the  xfd  win- 
dow appears. 


Killing  a Client  Window  with  xkill 

The  xkill  program  allows  you  to  kill  a client  window,  or  more  specifically,  to  force  the  server 
to  end  the  connection  to  the  client.  The  process  exits  and  the  associated  window  is  removed. 

xkill  is  a fairly  drastic  method  of  terminating  a client  and  should  not  be  used  as  the  method  of 
preference.  In  most  cases,  clients  can  be  terminated  in  other  ways.  The  possible  repercus- 
sions of  using  xkill  and  some  of  the  alternatives  are  discussed  in  the  next  section. 

xkill  is  intended  primarily  to  be  used  in  cases  where  more  conventional  methods  of  removing 
a client  window  do  not  work.  It  is  especially  useful  when  programs  have  displayed  undesired 
windows  on  the  screen.  To  remove  a stubborn  client  window,  type: 

% xkill 

on  the  command  line  of  an  xterm  window.  The  pointer  changes  to  a “draped  box”  pointer 
and  you  are  instructed  to: 

Select  the  window  whose  client  you  wish  to  kill  with  button  1 . . . 

Move  the  draped  box  pointer  to  the  window  you  want  to  remove,  as  in  Figure  7-12,  and  click 
the  first  pointer  button.  The  window  is  removed.  ( xkill  does  not  allow  you  to  select  the  root 
window.) 
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Figure  7-12.  Selecting  the  window  to  be  removed 

You  can  also  specify  the  window  to  be  killed  by  its  resource  ID.  Every  window  has  an  iden- 
tification number  associated  with  it.  The  xwininfo  client  can  be  used  to  display  a window’s 
resource  ID  (see  the  section  “Window  and  Display  Information”  later  in  this  chapter). 

To  remove  a window  using  its  ID  number,  type: 

% xkill  -id  number 

The  window  with  the  ID  number  is  removed.  Killing  a window  by  its  ID  number  is  more 
cumbersome,  but  it’s  somewhat  safer  than  choosing  the  window  to  be  killed  with  the  pointer. 
It’s  too  easy  to  click  in  the  wrong  place.  (Of  course,  it’s  less  treacherous  to  use  the  pointer 
on  an  isolated  window  than  a window  in  a stack.) 


Problems  with  Killing  a Client 

The  most  obvious  problem  with  xkill  is  that  it’s  possible  to  kill  the  wrong  window  inadver- 
tently. Perhaps  less  obvious  is  a problem  inherent  in  ‘killing’  a program.  As  a general  rule,  a 
command  that  ‘kills’  a program  does  not  give  the  program  time  to  save  or  complete  processes 
that  are  still  running — in  effect,  to  clean  up  after  itself.  The  processes  that  can  be  adversely 
affected  may  be  visible  to  the  user,  like  an  editing  session,  or  they  may  be  underlying  system 
processes,  like  writing  to  or  reading  from  a socket. 
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Most  clients  can  be  terminated  in  ways  that  allow  them  to  finish  all  relevant  processes  and 
then  exit  cleanly.  These  methods  should  be  attempted  before  you  use  xkill , or  some  other 
program  that  kills  the  client. 

For  example,  you  can  generally  remove  an  xterm  window  by  typing  in  the  window  the  same 
command  you  use  to  log  off  the  system.  You  should  also  be  able  to  remove  an  xterm  window 
with  various  Main  Options  menu  commands,  depending  on  the  signals  that  can  be  interpreted 
by  your  system.  (Some  of  these  signals,  such  as  SIGHUP  and  SIGTERM,  are  more  gentle  to 
the  system.  See  the  xterm  reference  page  in  Part  Three  of  this  guide  for  a list  of  menu  com- 
mands and  the  signals  they  send.)  An  xcalc  window  can  generally  be  removed  by  typing  q, 
Q,  or  Control-C  in  the  window.  A bitmap  window  has  a Quit  button  box,  etc.  If  you  are  run- 
ning Release  4 of  X,  the  Twm  menu  also  provides  an  item,  Delete,  which  allows  you  to  safely 
remove  a client  window  if  the  client  has  been  written  to  comply  with  standard  interclient 
communication  conventions.  (See  Chapter  3,  Using  the  twm  Window  Manager , for  details.) 

A few  clients,  such  as  oclock,  cannot  be  removed  except  by  killing.  You  must  use  xkill , or  a 
similar  method,  to  remove  an  oclock  window. 

Generally,  however,  you  should  exhaust  the  safer  alternatives  before  you  use  xkill  and  other 
commands  that  kill  a client. 

When  you  want  to  remove  a window,  depending  on  the  client  and  what  commands  it  recog- 
nizes, try  the  following  methods  (roughly)  in  this  order: 

1 . Methods  that  cause  the  client  to  exit  after  finishing  relevant  processes: 

a.  Special  commands  (e.g.,  logout,  exit)  or  key  sequences  (e.g.,  Control-D,  Con- 
trol-C, q,  Q)  recommended  to  stop  a client. 

b.  Certain  application-specific  menu  items  (e.g.,  for  x term,  the  Main  Options  menu  com- 
mands Send  HUP  Signal,  Send  TERM  Signal,  and  Quit;  the  bitmap  Quit  box). 

c.  The  Delete  item  on  the  Twm  menu.  (Whether  this  works  depends  on  whether  the  cli- 
ent to  be  removed  has  been  written  to  comply  with  the  interclient  communication 
conventions.  If  other  safe  methods  have  failed  and  Delate  doesn  t work,  you  may 
need  to  take  more  drastic  measures.) 

2.  When  these  methods  don’t  work,  or  don’t  apply  (as  in  the  case  of  oclock ),  then  use  com- 
mands or  menu  items  that  kill  the  client: 

a.  The  Send  KILL  Signal  item  on  the  xterm  Main  Options  menu,  for  removing  xterm  win- 
dows only  (see  Chapter  4,  The  xterm  Terminal  Emulator). 

b.  The  Kill  item  on  the  Twm  menu  (see  Chapter  3,  Using  the  twm  Window  Manager).  (If 
you  are  running  Release  3 of  X,  you  can  use  the  KillWindow  item  on  the  uwm  Window- 
Ops  menu.  See  Appendix  B,  The  uwm  Window  Manager , for  details.) 
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c.  The  UNIX  kill  command  with  the  client’s  process  id  number,  which  is  determined 
using  ps.  (This  method  of  removing  a window  is  described  for  xclock  in  Chapter  2, 
Getting  Started*) 

d.  The  xkill  client. 


Be  warned  that  older  versions  of  xkill  can  have  surprising  complications.  For  example,  some 
older  versions  of  xkill  do  not  seem  to  work  properly  with  the  window  manager  twm.  twm 
automatically  becomes  the  parent  process  of  all  the  top  level  windows  in  the  window  hierar- 
chy. (See  the  discussion  of  xlswins  later  in  this  chapter  for  more  information  about  the  win- 
dow hierarchy.)  If  you  use  xkill  to  kill  a top  level  window,  twm  is  killed  instead,  and  the  win- 
dow remains.  Most  problems  such  as  these  should  have  been  solved  as  of  Release  3. 


Window  and  Display  Information  Clients 

The  standard  release  of  X includes  four  clients  that  provide  information  about  windows  on 
the  display  and  about  the  display  itself.  Much  of  the  information  is  probably  more  relevant 
to  a programmer  than  to  the  typical  user.  However,  these  clients  also  provide  certain  pieces 
of  information,  such  as  window  geometry,  window  ID  numbers,  and  the  number  and  nature  of 
screens  on  the  display,  that  can  assist  you  in  using  other  clients. 


Displaying  Information  about  a Window:  xwininfo 

The  xwininfo  client  displays  information  about  a particular  window.  As  described  in  Chapter 
8,  Command  Line  Options,  much  of  this  information  is  useful  in  determining  or  setting  win- 
dow geometry,  xwininfo  also  provides  you  with  the  window  ID  (also  called  the  resource  ID). 
Each  window  has  a unique  identification  number  associated  with  it  This  number  can  be  used 
as  a command  line  argument  with  several  clients.  Most  notably,  the  window  ID  can  be  sup- 
plied to  the  xkill  client  to  specify  the  window  be  killed.t 

To  display  information  about  a window,  type  the  following  command  in  an  xterm  window: 

% xwininfo 

The  pointer  changes  to  the  crosshair  pointer,  and  you  are  directed  to  select  the  window  about 
which  you  want  information: 


*This  method  is  powerful,  but  in  practice  has  limitations.  Many  versions  of  UNIX  only  allow  you  to  kill  a process  if 
you  are  the  owner  of  the  process  or  if  you  are  root.  Thus,  if  a client  has  been  started  on  your  display  from  a remote 
system,  and  you  don’t  know  the  root  password,  you  may  not  be  in  a position  to  use  the  UNIX  kill  command. 
fYou  can  also  use  the  window  ID  as  an  argument  to  the  xprop  client,  which  displays  various  window  “properties.”  A 
property  is  a piece  of  information  associated  with  a window  or  a font  Properties  facilitate  communication  between 
clients  via  the  server.  They  are  used  by  clients  to  store  information  that  other  clients  might  need  to  know,  and  to  read 
that  information  when  it  is  provided  by  other  clients.  See  the  xprop  reference  page  in  Part  Three  of  this  guide,  and 
Volume  On  t,Xlib  Programming  Manual  for  more  information  about  properties  and  the  xprop  client. 
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xwininfo  > Please  select  the  window  about  which  you 
==>  would  like  information  by  clicking  the 
==>  mouse  in  that  window. 

You  can  select  any  window  on  the  display,  including  the  window  in  which  you’ve  typed  the 
command  and  the  root  window.  (Rather  than  using  the  pointer,  you  can  specify  a window  on 
the  command  line  by  supplying  its  title,  or  name,  if  it  has  no  title,  as  an  argument  to 
xwininfo  s own  -name  option.  See  Chapter  8,  Command  Line  Options,  for  information 
about  setting  a client’s  title  and  name.  See  the  xwininfo  reference  page  in  Part  Three  of  this 
guide  for  a list  of  its  options.) 


Figure  7-13  shows  the  statistics  the  Release  4 version  of  xwininfo  supplies,  with  some  typical 
readings. 


xwininfo  ==>  Window  id:  0x40000f  (xterm) 


==>  Absolute  upper-left  X:  0 

==>  Absolute  upper-left  Y:  0 

==>  Relative  upper-left  X:  0 

==>  Relative  upper-left  Y:  21 

==>  Width:  578 

==>  Height:  316 

==>  Depth:  1 

==>  Border  width:  1 

==>  Window  class:  InputOutput 

==>  Colormap:  0x80065 

==>  Window  Bit  Gravity  State:  NorthWestGravity 

==>  Window  Window  Gravity  State:  NorthWestGravity 

==>  Window  Backing  Store  State:  NotUseful 

==>  Window  Save  Under  State:  no 

==>  Window  Map  State:  IsViewable 

==>  Window  Override  Redirect  State:  no 

==>  Corners:  +0+0  -572+0  -572-582  +0-582 

Figure  7-13.  Window  information  displayed  by  xwininfo 


These  readings  are  for  a login  xterm  window  displayed  using  a 12  point  Roman  Courier  font. 
All  numerical  information  is  in  pixels,  except  depth,  which  is  in  bits  per  pixel.  The  twm  win- 
dow manager  is  also  running.  The  statistics  that  are  most  significant  for  the  average  user  are 
listed  below: 


xwininfo  ==>  Window  id:  0x40000f  (xterm) 


==>  Absolute  upper-left  X:  0 

==>  Absolute  upper-left  Y:  0 

==>  Relative  upper-left  X:  0 

==>  Relative  upper-left  Y:  21 

==>  Width:  578 

==>  Height:  316 

==>  Depth:  1 

==>  Border  width:  1 

==>  Colormap:  0x80065 

==>  Corners:  +0+0  —572+0  —572—582  +0—582 


The  first  piece  of  information  is  the  window  ID,  which  can  be  used  as  an  argument  to  xkill. 
Specifying  the  window  to  be  killed  by  its  ID  number  is  somewhat  less  risky  than  choosing  it 
with  the  pointer. 
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The  other  statistics  (with  the  exception  of  depth)  can  be  used  to  gauge  the  window’s  geome- 
try (size  and  position).  The  absolute  upper-left  X and  Y correspond  to  the  positive  x and  y 
offsets  of  the  window  from  the  root  window.  These  figures  can  be  used  on  the  command  line 
to  specify  window  placement,  as  described  in  Chapter  8,  Command  Line  Options. 

The  relative  upper-left  X and  Y are  significant  only  if  you’re  running  a window  manager, 
such  as  twm,  that  provides  some  sort  of  frame.  The  relative  upper-left  X and  Y are  the  win- 
dow’s x and  y offsets  relative  to  its  frame.  In  this  example,  the  relative  upper-left  Y of  21 
pixels  refers  to  the  height  of  the  window’s  titlebar. 

The  four  comers  are  listed  with  the  upper  left  comer  first  and  the  other  three  clockwise 
around  the  window  (i.e.,  upper  right,  lower  right,  lower  left).  The  upper  left  comer  always 
gives  the  positive  x and  y offsets  for  the  window.  The  width  and  height  in  pixels  are  some- 
what less  useful,  since  the  geometry  option  to  xterm  requires  that  these  figures  be  specified  in 
characters  and  lines.  See  Chapter  8,  Command  Line  Options , for  more  information  about 
window  geometry  and  how  to  set  it  based  on  the  results  of  xwininfo. 

The  values  for  window  depth  and  colormap  relate  to  how  color  is  specified.  See  the  discus- 
sion of  color  in  Chapter  8 for  more  information. 

Be  aware  that  the  Release  3 version  of  xwininfo  docs  not  provide  relative  x and  y offsets.  It 
does  provide  absolute  x and  y offsets,  though  they  are  labeled  simply  as: 

==>  Upper  left  X:  0 
==>  Upper  left  Y:  0 


The  other  statistics  provided  by  xwininfo  are  listed  below: 


==> 

==> 

==> 

==> 

==> 

==> 

==> 


Window  class:  InputOutput 

Window  Bit  Gravity  State:  NorthWestGravity 
Window  Window  Gravity  State:  NorthWestGravity 
Window  Backing  Store  State:  NotUseful 
Window  Save  Under  State:  no 
Window  Map  State:  IsViewable 
Window  Override  Redirect  State:  no 


These  statistics  have  to  do  with  the  underlying  mechanics  of  how  a window  is  resized, 
moved,  obscured,  unobscured,  and  otherwise  manipulated.  They  are  inherent  in  the  client 
program  and  you  cannot  specify  alternatives.  For  more  information  on  these  and  other  win- 
dow attributes,  see  Chapter  4 in  Volume  One,  Xlib  Programming  Manual. 

You  can  also  use  xwininfo  with  various  options  to  display  other  window  attributes.  See  the 
reference  page  in  Part  Three  of  this  guide  for  details. 


Listing  the  Window  Tree:  xlswins 


Windows  are  arranged  in  a hierarchy,  much  like  a family  tree,  with  the  root  window  at  the 
top.  The  xlswins  client  displays  the  window  tree  starting  with  the  root  window,  listing  each 
window  by  its  resource  ID  and  title  (or  name),  if  it  has  one.  (See  Chapter  8,  Command  Line 
Options,  for  a discussion  of  setting  a client’s  title  and  name  with  command  line  options.) 
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A resource  ID  can  be  supplied  to  xkill  to  specify  the  window  to  kill.  You  can  also  supply  a 
resource  ID  to  xwininfo  to  specify  the  window  you  want  information  about,  or  to  xprop  to  get 
the  window’s  properties.  Being  able  to  display  the  ID  numbers  of  all  windows  on  the  screen 
at  once  is  especially  helpful  if  one  or  more  windows  is  obscured  in  the  stack.  The  xwininfo 
client  is  virtually  useless  in  situations  in  which  one  window  is  hidden  behind  another. 
xlswins  allows  you  to  determine,  by  process  of  elimination,  which  window  is  hidden — with- 
out having  to  circulate  all  the  windows  on  your  screen.  You  can  then  use  xwininfo  with  the 
ID  number  (displayed  by  xlswins ) to  get  information  about  the  obscured  window. 

Figure  7-14  shows  the  results  of  xlswins  for  a simple  window  arrangement:  a single  xterm 
(login)  window  on  a root  window. 

0x8006e  () 

0x30000e  (xterm) 

0x300015  () 

0x300016  () 

Figure  7- 1 4.  Window  tree  displayed  by  xlswins 

The  xterm  window  is  easily  identified.  Any  client  that  displays  a window,  such  as  xterm, 
xclock,  xfd , bitmap,  etc.,  will  be  listed  by  name  (in  parentheses)  following  the  ID  number* 
The  root  window  is  listed  above  the  xterm  in  the  window  hierarchy.  Client  (and  other)  win- 
dows displayed  on  the  root  window  are  called  children  of  the  root  window,  in  keeping  with 
the  family  tree  analogy.  Thus,  the  root  window  is  the  parent  of  the  xterm  window.  In  the 
xlswins  listing,  a child  window  is  indented  once  under  its  parent 

But  what  are  the  other  windows  listed  in  Figure  7-14?  A superficial  examination  of  these 
other  windows  provides  a brief  introduction  to  the  inner  workings  of  X.  An  underlying  fea- 
ture of  X is  that  menus,  boxes,  icons,  and  even  features  of  client  windows,  such  as  scrollbars, 
are  actually  windows  in  their  own  right.  What’s  more,  these  windows  (and  client  window 
icons)  may  still  be  considered  to  exist,  even  when  they  are  not  displayed. 

The  two  remaining  windows  are  unnamed.  From  the  relative  indents  of  the  windows,  we  can 
tell  certain  information.  The  first  unnamed  window  is  a child  of  the  xterm,  the  second  is  a 
child  of  the  child. 

If  we  again  run  xlswins,  this  time  requesting  a long  listing  (with  the  -1  option),  we  get  geom- 
etry information  that  helps  identify  each  window,  as  shown  in  Figure  7-15. 

0:  0x8006e  ()  1152x900+0+0  +0+0 

1:  0x30000e  (xterm)  818x484+0+0  +0+0 

2:  0x300015  ()  818x484+0+0  +1+1 

3:  0x300016  ()  14x484+-l+-l  +0+0 


Figure  7-15.  Window  tree  with  geometry  specifications 


The  first  number  on  each  line  refers  to  the  level  of  the  window  in  the  hierarchy,  the  root  win- 
dow  being  al  level  0,  client  windows  at  1.  etc.  The  first  geometry  string  is  the  complete 


♦Most  likely,  you  will  not  have  to  deal 
dows.  You  can  use  the  IDs  of  the  client 


with  the  ID  numbers  for  windows  other  than  the  explicitly  named  client  win 
windows  in  all  of  the  ways  we’ve  discussed:  with  xkill,  xwininfo,  xprop,  etc. 
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specification  relative  to  the  parent  window.  The  second  geometry  string  is  the  current  posi- 
tion relative  to  the  root  window.  A window  at  coordinates  0,0  would  have  the  position  +0+0 
relative  to  the  root.  The  two  unnamed  windows  under  xterm  are  the  VT102  window  and  the 
window’s  scrollbar,  respectively.  (The  first  xterm  listing  is  the  application  shell  window, 
which  can  be  displayed  both  as  a VT102  and  a Tektronix  window.) 

The  listing  in  Figure  7-15  was  generated  when  the  twm  window  manager  was  not  running. 
Many  of  the  features  provided  by  twm,  such  as  the  window  “frame”  and  its  command  but- 
tons, the  icon  manager,  and  menus,  are  actually  all  windows.  This  greatly  complicates  the 
window  hierarchy.  If  you  run  xlswins  while  twm  is  running,  you  can  assume  that  most  of  the 
mysterious  windows  in  the  hierarchy  are  features  provided  by  the  window  manager. 

For  more  information  on  the  window  hierarchy,  see  Volume  One,  Xlib  Programming  Manual. 


Listing  the  Currently  Running  Clients:  xlsclients 

You  can  get  a listing  of  the  client  applications  running  on  a particular  display  by  using 
xlsclients.  Without  any  options,  xlsclients  displays  a two-column  list,  similar  to  the  follow- 
ing: 

colorful  xterm  -geometry  80x24+10+10  -Is 
colorful  xclock  -geometry  -0-0 

The  first  column  shows  the  name  of  the  display  (machine)  and  the  second  the  client  running 
on  it.  The  client  is  represented  by  the  command  line  used  to  initiate  the  process. 

This  sample  listing  indicates  that  there  is  one  xterm  window  and  one  xclock  window  running 
on  the  display  colorful.  (The  option  -Is  following  the  xterm  command  reveals  that  the 
shell  running  in  this  window  is  a login  shell.)  The  list  is  alphabetical. 

You  can  use  xlsclients  to  create  an  jcsession  file,  which  specifies  the  clients  you  want  to  be 
run  automatically  when  you  log  in.  In  order  to  do  this,  you  must  have  set  up  client  windows 
in  an  arrangement  you  like  using  command  line  options  alone  (that  is,  without  having  moved 
or  resized  windows  via  the  window  manager).  You  can  then  run  xlsclients  to  print  a sum- 
mary of  the  command  lines  you  used  to  set  up  the  display  and  include  those  command  lines 
in  your  jcsession  file.  See  Appendix  A,  System  Management , for  information  on  setting  up  a 
user  session. 

By  default,  xlsclients  lists  the  clients  running  on  the  display  corresponding  to  the  DISPLAY 
environment  variable,  almost  always  the  local  display.  You  can  list  the  clients  running  on 
another  display  by  using  the  -display  command  line  option.  See  Chapter  8,  Command 
Line  Options,  for  details. 

With  the  option  -1  (indicating  long),  xlsclients  generates  a more  detailed  listing.  Figure 
7-16  shows  the  long  version  of  the  listing  above. 

For  each  client,  xlsclients  displays  six  items  of  information:  the  window  ID  number,  machine 
name,  client  name,  icon  name,  command  line  used  to  run  the  client,  and  what  are  known  as 
the  instance  and  class  resource  names  associated  with  the  client. 
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Window  0x30000e: 

Machine:  colorful 

Name:  xterm 

Icon  Name:  xterm 

Command:  xterm  -geometry  80x24+10+10  -Is 

Instance/Class:  xterm/XTerm 

Window  0x40000b: 

Machine:  colorful 

Name:  xclock 

Icon  Name:  xclock 

Command:  xclock  -geometry  -0-0 

Instance/Class:  xclock/XClock 


Figure  7-16.  Long  xlsclients  listing 

As  we’ll  see  in  Chapter  8,  Command  Line  Options,  many  clients,  including  xterm,  allow  you 
to  specify  an  alternate  name  for  a client  and  a title  for  the  client’s  window.  If  you’ve  speci- 
fied a title,  it  will  appear  in  the  xlsclients  Name  field.  If  you  haven’t  specified  a title,  but 
have  specified  a name  for  the  application,  the  name  will  appear  in  this  field.  Neither  of  the 
clients  in  the  sample  display  has  been  given  an  alternate  name  or  title. 

You  use  the  instance  and  class  resource  names  to  specify  default  window  characteristics,  gen- 
erally by  placing  them  in  a file  in  your  home  directory.  This  is  described  in  detail  in  Chapter 
9,  Setting  Resources. 

Generating  Information  about  the  Display:  xdpyinfo 

The  xdpyinfo  client  gives  information  about  the  X display,  including  the  name  of  the  display 
(contents  of  the  DISPLAY  variable),  version  and  release  of  X,  number  of  screens,  current 
screen,  and  statistics  relating  to  the  color,  resolution,  input,  and  storage  capabilities  of  each 
screen.  The  xdpyinfo  reference  page  in  Part  Three  of  this  guide  shows  a listing  for  a display 
that  supports  both  a color  and  monochrome  screen. 

Much  of  the  information  provided  by  xdpyinfo  has  to  do  with  how  clients  communicate  infor- 
mation to  one  another  and  is  more  relevant  to  a programmer  than  to  the  typical  user.  How- 
ever, the  basic  statistics  about  the  name  of  the  display,  the  version  and  release  of  X,  and  the 
number  and  nature  of  screens  might  be  very  helpful  to  a user,  particularly  one  who  is  using  a 
display  for  the  first  time. 

In  addition,  the  detailed  information  about  each  screen’s  color  capabilities  can  also  be  very 
valuable  in  learning  how  to  use  color  more  effectively.  This  information  includes  the  default 
number  of  colormap  cells:  the  number  of  colors  you  can  use  on  the  display  at  any  one  time. 
See  Chapter  8,  Command  Line  Options,  for  more  information  on  the  use  of  color  and  how  to 
specify  colors  for  many  clients. 

See  Volume  One,  Xlib  Programming  Manual,  for  insights  into  some  of  the  other  information 
provided  by  xdpyinfo. 
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User-contributed  Clients 


In  addition  to  the  clients  in  the  standard  MIT  X distribution,  there  are  many  user-contributed 
clients  available  in  the  X source  tree,  distributed  over  Usenet,  and  perhaps  included  with  var- 
ious commercial  distributions.  If  you  have  access  to  Usenet,  the  newsgroup  comp. window sjc 
contains  voluminous  discussions  of  X programming  and  the  newsgroup  comp. sour ces.x  con- 
tains sources. 

Prior  to  Release  4,  uwm  (the  universal  window  manager)  was  the  official  window  manager 
shipped  with  the  standard  X Window  System.  As  of  Release  4,  uwm  is  no  longer  supported, 
but  is  still  available  as  a user-contributed  client.  However,  be  aware  that  uwm  does  not  com- 
ply with  accepted  interclient  communication  conventions  and  thus,  should  probably  not  be 
the  window  manager  of  choice. 

Several  other  window  managers  are  widely  used  and  have  been  tailored  to  reflect  the  inter- 
client communication  conventions  proposed  in  Release  3.  Some  of  the  more  popular  window 
managers  that  reflect  these  conventions  are: 

awm  Ardent  window  manager  (written  by  Jordan  Hubbard  of  Ardent  Computer 

Corporation). 

rtl  Tiled  window  manager  (written  by  Ellis  Cohen  at  Siemens  Research  & 

Technology  Laboratories,  RTL). 

olwm  OPEN  LOOK  window  manager  (developed  by  AT&T). 

mwm  Motif  window  manager  (written  by  Ellis  Cohen  at  the  Open  Software 

Foundation). 

Appendix  C,  The  OSF I Motif  Window  Manager , discusses  mwm  in  greater  detail. 

Commercial  products  (such  as  spreadsheets,  word  processors,  and  graphics  or  publishing 
applications)  based  on  the  X Window  System  are  also  becoming  available. 


X Toolkit  Applications 

Many  clients  have  been  written  (or  rewritten)  with  a programming  library  called  the  X 
Toolkit.  The  X Toolkit  provides  a number  of  predefined  components  called  widgets.  Widg- 
ets make  it  easier  to  create  complex  applications;  they  also  ensure  a consistent  user  interface 
between  applications. 

Most  of  the  clients  described  in  this  guide  were  written  before  the  X Toolkit  was  fully  devel- 
oped. Although  they  have  since  been  rewritten  to  use  the  X Toolkit,  they  don’t  necessarily 
make  full  use  of  all  its  features. 

However,  most  of  the  standard  clients  use  enough  of  these  features  that  you  can  see  what  to 
expect  from  future  applications  that  are  based  more  fully  on  the  X Toolkit 
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This  section  briefly  reviews  some  features  of  X Toolkit  applications,  with  reference  to  where 
they  are  implemented  in  the  current  crop  of  clients.  For  a comprehensive  treatment  of  the  X 
Toolkit,  see  Volumes  Four  and  Five,  X Toolkit  Intrinsics  Programming  Manual  and  X Toolkit 
Intrinsics  Reference  Manual. 


Dialog  Boxes  and  Command  Buttons 

A dialog  box  is  used  when  an  application  requires  a small  piece  of  information  from  the  user, 
such  as  a filename.  A dialog  box  typically  has  three  elements:  it  always  has  the  first  element, 
and  may  or  may  not  have  the  second  and/or  third  elements  in  the  following  list: 

A prompt  that  identifies  the  purpose  of  the  widget  This  might  be  as  simple  as  the  string 
“Filename:”. 

• An  area  in  which  you  can  type  your  response. 

• Command  buttons  that  allow  you  to  confirm  or  cancel  the  dialog  input. 

A dialog  box  is  usually  a pop-up  window,  which  goes  away  after  the  required  information  is 
provided. 

The  X client  bitmap  is  one  of  the  few  current  applications  that  use  a dialog  box.  It  displays 
the  dialog  displayed  in  Figure  7-17  when  you  quit  the  application.  Future  X applications  can 
be  expected  to  make  far  more  extensive  use  of  dialogs  like  this. 


Save  changes  before  quitting? 


Yes 

No 

Cancel 

Figure  7-17.  A dialog  box  with  Yes,  No,  and  Cancel  command  buttons 

Each  command  button  in  the  box  is  itself  a widget.  A command  button  is  a rectangle  that 
contains  a text  label.  When  the  pointer  is  on  the  button,  its  border  is  highlighted  to  indicate 
that  the  button  is  available  for  selection.  When  a pointer  button  is  clicked,  some  action 
(presumably  indicated  by  the  label)  is  performed  by  the  program. 

Some  applications  use  the  following  convention  for  command  buttons.  Whenever  you  press 
a button  that  may  cause  you  to  lose  some  work  or  is  otherwise  dangerous,  a second  dialog 
box  will  appear  asking  you  to  confirm  the  action.  This  dialog  box  will  contain  an  Abort  but- 
ton and  a Confirm  button.  Pressing  the  Abort  button  cancels  the  operation,  and  pressing  the 
Confirm  button  will  proceed  with  the  operation. 
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(A  very  handy  shortcut  exists  in  some  applications:  if  you  press  the  original  button  again,  it 
will  be  interpreted  as  a Confirm.  If  you  press  any  other  command  button,  it  will  be  inter- 
preted as  an  Abort.) 


Scrollbars 

As  described  in  the  discussion  of  xterm  in  Chapter  4,  The  xterm  Terminal  Emulator,  applica- 
tions can  use  a scrollbar  to  move  up  and  down  through  data  that  is  too  large  to  fit  in  a win- 
dow. A scrollbar  is  an  X Toolkit  widget. 

The  scrollbar  consists  of  a sliding  bar  (often  called  the  thumb ) within  a columnar  slide 
region.  The  size  of  the  thumb  within  the  scrollbar  corresponds  to  the  amount  of  the  data 
displayed  within  the  visible  portion  of  the  window  with  respect  to  the  entire  body  of  data.  If 
no  data  has  yet  been  displayed  in  the  window,  the  thumb  fills  the  entire  scrolling  region,  as 
shown  in  Figure  7-18. 

x term  uses  a vertical  scrollbar;  other  applications  may  use  a horizontal  scrollbar,  or  both. 
One  type  of  widget  that  can  have  both  horizontal  and  vertical  scrollbars  is  called  a viewport. 

When  the  pointer  is  moved  into  the  scrollbar,  the  cursor  appears  as  an  arrow  that  points  in  the 
direction  that  scrolling  can  occur.  If  scrolling  can  occur  in  either  direction,  the  cursor 
appears  as  a two-headed  arrow. 

When  the  middle  pointer  button  is  clicked  at  any  point  in  the  scrollbar,  the  thumb  moves  to 
that  point,  and  the  data  in  the  window  scrolls  to  the  corresponding  position.  When  the 
middle  pointer  button  is  pressed  and  held  down,  the  thumb  can  be  “dragged”  to  a desired 
position  in  the  scrollbar.  If  you  click  the  first  (left)  button  in  the  scrollbar,  the  data  in  the 
window  scrolls  up,  toward  the  end  of  the  information  in  the  window.  If  you  click  the  third 
(right)  button,  the  data  in  the  window  scrolls  down,  towards  the  beginning  of  the  information 
in  the  window. 


Selecting  Information  for  Copying  and  Pasting 

As  described  in  the  discussion  of  xterm  in  Chapter  4,  when  you  select  contents  from  one  file, 
those  contents  become  the  PRIMARY  selection,  which  is  available  to  other  clients.  For 
example,  you  can  select  text  in  one  xterm  window  and  paste  the  text  into  any  other  xterm 
window.  See  Chapter  4,  The  xterm  Terminal  Emulator,  for  a complete  discussion  of  copying 
and  pasting.  In  applications  written  with  the  X Toolkit,  selections  are  a method  of 
widget-to-widget  communication. 
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Figure  7-18.  An  xterm  window  with  scrollbar 


Vertical  Panes 


A VPaned  widget  arranges  a series  of  windows  one  above  the  other  without  overlapping 
they  are  vertically  tiled). 


(i.e., 


A small  region,  called  a grip,  appears  on  the  border  between  each  subwindow.  When  the 
pointer  is  positioned  on  the  grip  and  a button  pressed,  an  arrow  is  displayed  that  indicates  the 
direction  in  which  the  border  between  the  two  windows  can  be  moved.  If  you  move  the 
pointer  in  the  direction  of  the  arrow  (while  keeping  the  button  depressed),  one  subwindow 
will  grow,  while  the  other  will  shrink. 


The  individual  panes  can  be  any  other  type  of  widget.  For  example,  the  xmh  mail  handler 
includes  dialog  boxes  with  buttons,  viewports  containing  text  widgets  and  so  on,  as  shown  in 
Figure  7-19.  (We  refer  to  the  xmh  client  solely  to  illustrate  vertical  panes  that  can  be  used  by 
other  X clients.  The  current  xmh  client  is  not  discussed  in  this  guide.) 
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Viewports 

A viewport  is  a composite  widget  that  provides  a main  window  and  horizontal  and/or  vertical 
scrollbars,  xman  is  an  application  that  uses  a viewport  widget,  as  illustrated  by  Figure  7-20. 


Text  Editing  Widget 

Many  applications  include  one  or  more  areas  in  which  you  can  enter  text  All  such  text  entry 
areas  support  the  same  set  of  editing  commands.  At  this  point,  xedit,  xmh,  and  several  user- 
contributed  clients  use  the  text  widget. 

In  applications  (such  as  xedit ) that  use  the  text  widget,  various  Control  and  Meta  keystroke 
combinations  are  bound  to  a set  of  commands  similar  to  those  provided  by  the  emacs  text 
editor.*  In  addition,  the  pointer  buttons  may  be  used  to  select  a portion  of  text  or  to  move  the 
insertion  point  in  the  text.  Pressing  the  first  pointer  button  (usually  the  left  button)  causes  the 
insertion  point  to  move  to  the  pointer.  Double-clicking  the  first  button  selects  a word,  triple- 
clicking selects  a paragraph,  and  quadruple-clicking  selects  everything.  Any  selection  may 
be  extended  in  either  direction  by  using  the  third  pointer  button  (usually  the  right). 

*The  commands  may  be  bound  to  keys  different  from  the  defaults  described  below  through  the  standard  X Toolkit 
key  rebinding  mechanisms. 
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Figure  7-20.  xman  uses  a viewport  widget 

In  the  following  list  of  commands,  a line  refers  to  one  displayed  row  of  characters  in  the  win- 
dow. A paragraph  refers  to  the  text  between  manually  inserted  carriage  returns  or  blank 
lines.  Text  within  a paragraph  is  automatically  broken  into  lines  based  on  the  current  width 
of  the  window. 

In  Release  4 of  X,  the  following  keystroke  combinations  are  defined  as  indicated.  (Note  that 
“Control”  and  “Meta”  are  two  of  the  “soft”  key  names  X recognizes.  They  are  mapped  to 
particular  physical  keys  which  may  vary  from  keyboard  to  keyboard.  See  the  “xmodmap” 
section  in  Chapter  11,  Setup  Clients,  for  a discussion  of  modifier  key  mapping.)  If  you  are 
using  an  earlier  release  of  X,  a few  of  the  following  keystroke  combinations  may  produce 
slightly  different  results. 
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Control-A 

Move  to  the  beginning  of  the  current  line. 

Control-B 

Move  backward  one  character. 

Control-D 

Delete  the  next  character. 

Control-E 

Move  to  the  end  of  the  current  line. 

Control-F 

Move  forward  one  character. 

Control-H,  or 
Backspace 

Delete  the  previous  character. 

Control, 
Control-M, 
LineFeed,  or 
Return 

New  paragraph. 

Control-K 

Kill  the  rest  of  this  line. 

Control-L 

Redraw  this  window. 

Control-N 

Move  down  to  the  next  line. 

Control-O 

Divide  this  line  into  two  lines,  at  this  point. 

Control-P 

Move  up  to  the  previous  line. 

Control-V 

Move  down  to  the  next  screenful  of  text 

Control-W 

Kill  the  selected  text 

Control-Y 

Insert  the  last  killed  text 

Control-Z 

Scroll  the  text  one  line  up. 

Meta-< 

Move  to  the  beginning  of  the  file. 

Meta-> 

Move  to  the  end  of  the  file. 

Meta-[ 

Move  backward  one  paragraph. 

Meta-] 

Move  forward  one  paragraph. 

Meta-B 

Move  backward  one  word. 

Meta-D 

Kill  the  next  word. 

Meta-F 

Move  forward  one  word. 

Meta-H,  or 
Meta-Delete 

Kill  the  previous  word. 

Meta-I 

Insert  a file.  If  any  text  is  selected,  use  the  selected  text  as  the 
filename.  Otherwise,  a dialog  box  will  appear  in  which  you  can  type 
the  desired  filename. 

Meta-V 

Move  up  to  the  previous  screenful  of  text. 
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Meta-Y 

Meta-Z 

Delete 


Insert  the  last  selected  text  here.  Note  that  this  can  be  text  selected  in 
some  other  text  subwindow.  Also,  if  you  select  some  text  in  an  xterm 
window,  it  may  be  inserted  in  an  xmh  window  with  this  command. 
Pressing  pointer  button  2 is  equivalent  to  this  command. 

Scroll  the  text  one  line  down. 

Delete  the  previous  character. 
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Part  Two: 

Customizing  X 


X has  been  designed  to  put  the  user  in  the  driver’s  seat.  Everything  from  the 
colors  and  sizes  of  windows  to  the  contents  of  twm  menus  can  be  custom- 
ized by  the  user.  This  part  of  the  book  tells  you  how  to  reshape  X to  your 
liking. 


Command  Line  Options 
Setting  Resources 

Customizing  the  twm  Window  Manager 
Setup  Clients 


■ 
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Command  Line  Options 

This  chapter  describes  command-line  options  that  are  common  to  most  cli- 
ents. Some  arguments  to  command-line  options  can  also  be  specified  as  the 
values  of  resource  variables,  described  in  Chapter  9.  For  example,  the  for- 
mat of  a geometry  string  or  a color  specification  is  the  same  whether  it  is 
specified  as  an  argument  to  an  option  or  as  the  value  of  a resource  definition. 

In  This  Chapter: 

Which  Display  to  Run  On  164 

Title  and  Name  165 

Window  Geometry  166 

Border  Width  168 

Color  Specification 169 

The  rgb.txt  File 169 

Release  4 Color  Names 170 

Release  3 Color  Names 172 

Alternative  Release  4 Color  Databases 172 

Hexadecimal  Color  Specification 172 

The  RGB  Color  Model 173 

How  Many  Colors  are  Available?  174 

Starting  a Client  Window  as  an  Icon 176 

Specifying  Fonts  on  the  Command  Line 176 

Reverse  Video 177 
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Command  Line  Options 


X allows  the  user  to  specify  numerous  (very  numerous!)  command  line  options  when  starting 
most  clients.  The  command  line  options  for  each  client  are  detailed  on  the  reference  pages  in 
Part  Three  of  this  guide. 

As  a general  rule,  all  options  can  be  shortened  to  the  shortest  unique  abbreviation.  For 
example,  -display  can  be  shortened  to  -d  if  there  is  no  other  option  beginning  with  “d.” 
(Note  that  while  this  is  true  for  all  the  standard  MIT  clients,  it  may  not  be  true  of  any  random 
client  taken  off  the  net.) 

In  addition  to  certain  client-specific  options,  all  applications  built  with  the  X Toolkit  accept 
certain  standard  options,  which  are  listed  in  Table  8-1.  (Some  non-Toolkit  applications  may 
also  recognize  these  options.)  The  first  column  gives  the  name  of  the  option,  the  second  the 
name  of  the  resource  to  which  it  corresponds  (see  Chapter  9,  Setting  Resources ),  and  the  third 
a brief  description  of  what  the  option  does.  This  chapter  discusses  some  of  the  more  com- 
monly used  Toolkit  options  and  demonstrates  how  to  use  them.  (For  the  syntax  of  the  other 
Toolkit  options,  see  the  X reference  page  in  Part  Three  of  this  guide.) 

The  options  -selectionTimeout  and  -xnllanguage  are  available  as  of  Release  4. 


Table  8-1.  Standard  Options 


Option 

Resource 

Description 

-bg 

-background 

background 

background 

Background  color  of  window. 

Background  color  of  window. 

-bd 

-bordercolor 

borderColor 

borderColor 

Color  of  window  border. 

Color  of  window  border. 

-bw 

-borderwidth 

borderWidth 

borderWidth 

Border  width  of  window  in  pixels. 

Border  width  of  window  in  pixels. 

-display 

display 

Display  for  client  to  run  on. 

-f  n 

-font 

font 

font 

Font  for  text  display. 

Font  for  text  display. 
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Table  8-1.  Standard  Options  (continued) 


Option 

Resource 

Description 

-fg 

-foreground 

foreground 

foreground 

Foreground  (drawing  or  text)  color  of  window. 
Foreground  (drawing  or  text)  color  of  window. 

-geometry 

geometry 

Geometry  string  for  window  size  and  placement. 

-iconic 

Start  the  application  in  iconified  form. 

-name 

name 

Specify  a name  for  the  application  being  run. 

-rv 

-reverse 

+ rv 

reverseVideo 

reverseVideo 

reverseVideo 

Reverse  foreground  and  background  colors. 
Reverse  foreground  and  background  colors. 

Don’t  reverse  foreground  and  background. 

-selectionTimeout 

selectionTimeout 

Timeout  in  milliseconds  within  which  two  com- 
municating applications  must  respond  to  one 
another  for  a selection  request. 

-synchronous 

+synchronous 

synchronous 

synchronous 

Enable  synchronous  debug  mode. 

Disable  synchronous  debug  mode. 

-title 

title 

Specify  a window  title  (e.g.,  to  be  displayed  in  a 
titlebar). 

-xnllanguage 

xnlLanguage 

The  language,  territory,  and  codeset  for  National 
Language  Support;  this  information  helps  resolve 
resource  and  other  filenames. 

-xrm 

value  of  next  arg 

Next  argument  is  a quoted  string  containing  a 
resource  manager  specification  as  described  in 
Chapter  9. 

Though  all  Toolkit  options  are  preceded  by  a minus  sign,  client-specific  options  may  or  may 
not  require  it.  See  the  reference  page  for  each  client  in  Part  Three  of  this  guide  for  the  syntax 
of  all  options. 


Which  Display  to  Run  On 

Generally,  the  results  of  a client  program  are  displayed  on  the  system  where  the  client  is  run- 
ning. However,  if  you  are  running  a client  on  a remote  system,  you  probably  want  to  display 
the  results  on  your  local  server. 

An  option  of  the  form: 

-display  [host] : server [. screen] 

can  be  used  to  tell  a client  which  server  to  display  results  on. 
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The  host  specifies  on  which  machine  to  create  the  window,  the  server  specifies  the 
server  number,  and  the  screen  specifies  the  screen  number.  Note  that  the  server  param- 
eter always  begins  with  a colon  (a  double  colon  after  a DECnet  node*),  and  that  the  screen 
parameter  always  begins  with  a period.  If  the  host  is  omitted  or  is  specified  as  unix,  the 
local  node  is  assumed.  If  the  screen  is  omitted,  screen  0 is  assumed. 

xterm  and  other  X clients  normally  get  the  host,  server,  and  screen  from  the  DISPLAY  envi- 
ronment variable.  (In  most  configurations,  DISPLAY  will  be  set  to  the  local  host,  server  0 and 
screen  0.) 

However,  you  may  want  to  specify  the  host,  server,  and  screen  explicitly.  You  can  do  this  for 
all  clients  by  resetting  the  value  of  the  DISPLAY  variable,  or  for  a single  invocation  of  a cli- 
ent by  using  the  -display  option. 

For  example: 

% xterm  -display  other_node: 0 . 0 & 

creates  an  xterm  window  on  screen  0 of  server  0 on  the  machine  named  other_node. 

Although  much  of  the  current  X Window  System  documentation  suggests  that  any  of  the 
parameters  to  the  -display  option  can  be  omitted  and  will  default  to  the  local  node,  server 
and  screen  0,  respectively,  we  have  not  found  this  to  be  true.  In  our  experience,  only  the 
host  and  screen  parameters  (and  the  period  preceding  screen ) can  be  omitted.  The 
colon  and  server  are  necessary  in  all  circumstances. 

The  -display  option  can  be  abbreviated  as  -d. 


Title  and  Name 


The  name  of  the  program  (as  known  to  the  server)  and  the  title  of  the  window  can  be  speci- 
fied on  the  command  line.  The  -title  option  allows  you  to  specify  a text  string  as  the  title 
of  the  application’s  window.  If  your  application  has  a titlebar,  or  if  the  window  manager  you 
are  using  puts  titlebars  on  windows,  this  string  will  appear  in  the  titlebar.  indow  titles  can 
be  useful  in  distinguishing  multiple  instances  of  the  same  application. 

The  -name  option  actually  changes  the  name  by  which  the  server  identities  the  program. 
Changing  the  name  of  the  application  itself  (with  the  -name  option)  affects  the  way  the 
application  interprets  resource  files.  This  option  is  discussed  further  in  Chapter  9,  Setting 
Resources.  If  a name  string  is  defined  for  an  application,  that  string  will  appear  as  the  appli- 
cation name  in  its  icon. 

If  you  display  information  about  currently  running  windows  using  the  xwimnfo  or ■ xlswins 
client,  title  strings  will  appear  in  parentheses  after  the  associated  window  ID  numbers.  ( 
there  is  no  title  string,  but  there  is  a name  string,  the  name  string  will  be  displayed.) 


*By  convention,  DECnet  node  names  end  with  a colon. 
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You  can  also  use  the  xwininfo  client  to  request  information  about  a particular  window  by 
title,  or  name,  if  no  title  string  is  defined,  using  that  application’s  own  -name  option.  See 
the  xlswins  and  xwininfo  reference  pages  in  Part  Three  and  the  section  “Window  and  Display 
Information  Clients”  in  Chapter  7,  Other  Clients,  to  learn  more  about  these  clients. 


Window  Geometry 

All  clients  that  display  in  a window  take  a geometry  option  that  specifies  the  size  and  loca- 
tion of  the  client  window.  The  syntax  of  the  geometry  option  is: 

-geometry  geometry 

The  -geometry  option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting 
option  that  begins  with  “g.” 

The  parameter  to  the  geometry  option  (geometry),  referred  to  as  a “standard  geometry 
string,”  has  the  form: 

wi dthxhei ght±xoff±yoff 

The  variables,  width,  height,  xoff  (x  offset),  and  yoff  (y  offset)  are  values  in  pixels 
for  many  clients.  However,  application  developers  are  encouraged  to  use  units  that  are 
meaningful  to  the  application.  For  example,  x term  uses  columns  and  rows  of  text  as  width 
and  height  values  in  the  xterm  window. 

You  can  specify  any  or  all  elements  of  the  geometry  string.  Incomplete  geometry  specifica- 
tions are  compared  to  the  resource  manager  defaults  and  missing  elements  are  supplied  by 
the  values  specified  there.  If  no  default  is  specified  there,  and  twm  is  running,  the  window 
manager  will  require  you  to  place  the  window  interactively. 

The  values  for  the  x and  y offsets  and  their  effects  arc  shown  in  Table  8-2. 

Table  8-2.  Geometry  specification  x and  y offsets 


Offset  Variables 

Description 

+xoff 

A positive  x offset  specifies  the  distance  the  left  edge  of  the  window  is 
offset  from  the  left  side  of  the  display. 

+yoff 

A positive  y offset  specifies  the  distance  the  top  edge  of  the  window  is 
offset  from  the  top  of  the  display. 

-xoff 

A negative  x offset  specifies  the  distance  the  right  edge  of  the  window 
is  offset  from  the  right  side  of  the  display. 

-yoff 

A negative  y offset  specifies  the  distance  the  bottom  edge  of  the  win- 
dow is  offset  from  the  bottom  of  the  display. 

For  example,  the  command  line: 

% xclock  -geometry  125x125-10+10  & 
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places  a clock  125x125  pixels  in  the  upper-right  comer  of  the  display,  10  pixels  from  both 
the  top  and  right  edge  of  the  screen. 

For  xterm,  the  size  of  the  window  is  measured  in  characters  and  lines.  (The  default  size  is  80 
characters  wide  by  24  lines  long.)  If  you  wanted  to  use  a large  VT100  window,  120  charac- 
ters wide  by  40  lines  long,  you  could  use  the  following  geometry  specification: 

% xterm  -geometry  120x40-10+350  & 

This  command  places  the  large  xterm  window  in  the  lower-right  comer,  10  pixels  from  the 
right  edge  of  the  screen  and  350  pixels  from  the  top  of  the  screen.  Figure  8-1  illustrates  win- 
dow offsets. 


( ~ — \ 


v / 

V / 


Figure  8- 1.  Window  offsets 

Several  clients,  including  xterm , allow  you  to  set  the  size  and  position  of  the  icon  or  alterna- 
tive window  using  resource  variables  (in  an  Xdefaults  or  other  resource  file).  See  the  appro- 
priate client  reference  pages  in  Part  Three  of  this  guide  for  a complete  list  of  available 
resources.  Refer  to  Chapter  9,  Setting  Resources , for  instructions  on  how  to  set  resources. 

You  should  be  aware  that,  as  with  all  user  preferences,  you  may  not  always  get  exactly  what 
you  ask  for.  Clients  are  designed  to  work  with  a window  manager,  which  may  have  its  own 
rules  for  window  or  icon  size  and  placement.  However,  priority  is  always  given  to  specific 
user  requests,  so  you  won’t  often  be  surprised. 
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Border  Width 


Many  clients  also  allow  you  to  specify  the  width  of  the  border  to  be  placed  around  the  win- 
dow. The  border  width  is  specified  in  pixels.  For  example: 

% xtorm  -bw  10  & 

sets  a border  of  10  pixels  around  the  xterm  window. 

You  will  have  to  experiment  to  get  a feeling  for  the  translation  between  the  number  of  pixels 
and  actual  sizes  and  distances.  It  will  vary,  depending  on  the  type  of  workstation  you  are 
using. 

If  you  are  experimenting  with  geometry  measurements,  use  the  xwininfo  client  to  display 
information  about  windows  on  the  screen. 

At  the  command  line  prompt  in  an  xterm  window,  type: 

% xwininfo 

and  then  click  on  the  window  for  which  you  want  to  display  information.  You  should  see  a 
display  which  gives  various  characteristics  about  the  window  in  question.  The  statistics  most 
relevant  to  window  geometry  are  listed  below,  with  some  typical  readings: 

Upper  left  X:  572 
Upper  left  Y : 582 
Width:  578 
Height:  316 
Depth:  1 
Border  width:  1 

Corners:  +572+582  -0+582  -0-0  +572-0 

All  numerical  information  is  in  pixels,  except  depth,  which  is  in  bits  per  pixel.  (See  the  dis- 
cussion of  color  later  in  this  chapter  for  the  significance  of  window  depth.)  The  upper  left  X 
and  Y coordinates  are  particularly  useful  for  setting  the  location  of  a window  using  the 
geometry  option.  Upper  left  X corresponds  to  the  positive  x offset  (+xoff)  and  upper  left  Y 
corresponds  to  the  positive  y offset  ( +yoff ). 

The  four  comers  are  listed  with  the  upper  left  comer  first  and  the  other  three  clockwise 
around  the  window  (i.e.,  upper  right,  lower  right,  lower  left).  The  upper  left  comer  (first  in 
the  list)  always  gives  the  positive  x and  y offsets  for  the  window.  In  other  words,  the  upper 
left  comer  specification  is  the  +xoff+y  off  part  of  the  geometry  string. 

The  width  and  height  in  pixels  are  somewhat  less  useful,  since  the  geometry  option  to  xterm 
requires  that  these  figures  be  specified  in  characters  and  lines.  The  readings  above  are  for  a 
standard  size  xterm  window  using  a 12  point  Roman  Courier  font.  However,  you  will 
undoubtedly  become  accustomed  to  thinking  in  terms  of  pixels  by  specifying  the  geometry  of 
other  clients. 

See  the  xwininfo  reference  page  in  Part  Three  and  the  section  “Window  and  Display  Informa- 
tion Clients”  in  Chapter  7,  Other  Clients,  for  more  details. 
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Color  Specification 


Many  clients  have  options  that  allow  you  to  specify  the  color  of  the  window  border,  back- 
ground, and  foreground  (the  color  text  or  graphic  elements  will  be  displayed  in).  These 
options  generally  have  the  form: 


-bg 

color 

Sets  the  background  color. 

-fg 

color 

Sets  the  foreground  color. 

-bd 

color 

Sets  the  border  color. 

By  default,  the  background  of  an  application  window  is  usually  white  and  the  foreground 
black,  even  on  color  workstations.  You  can  specify  a new  color  using  either  the  color  names 
listed  in  a system  file  called  rgb.txt  or  hexadecimal  values  representing  colors. 

In  the  next  section,  we’ll  take  a look  at  some  of  the  colors  available  in  the  rgb.txt  file.  For 
now,  let’s  consider  the  syntax  of  a command  line  specifying  an  xterm  to  be  displayed  in  three 
colors: 

% xtorm  -bg  lightblue  -fg  darkslat«grey  -bd  plum  & 

This  command  creates  an  xterm  window  with  a background  of  light  blue,  foreground  of  dark 
slate  grey,  and  window  border  of  plum  (all  colors  are  available  in  both  Releases  3 and  4). 

At  the  command  line,  a color  name  should  be  typed  as  a single  word  (for  example,  dark- 
slategrey).  However,  you  can  type  the  words  comprising  a color  name  separately  if  you 
enclose  them  in  quotes,  as  in  the  following  command  line: 

% xterm  -bg  "light  blue"  -fg  "dark  slate  grey"  -bd  plum  & 

As  we’ll  see,  the  rgb.txt  file  contains  variants  of  the  same  color  name  (for  example,  “navy 
blue”  and  “NavyBlue,”  or  “grey”  and  “gray”)  to  allow  a range  of  spelling,  spacing,  and  capi- 
talization on  the  command  line. 

Some  clients  allow  additional  options  to  specify  color  for  other  elements,  such  as  the  cursor, 
highlighting,  and  so  on.  See  the  appropriate  client  reference  pages  in  Part  Three  of  this  guide 
for  details. 

The  rgb.txt  File 

The  rgb.txt  file,  usually  located  in  /usr/lib/Xl  1 , is  supplied  with  the  standard  distribution  of  X 
and  consists  of  predefined  colors  assigned  to  specific  text  names. 

A corresponding  compiled  file  called  rgb.dir  contains  the  definitions  used  by  the  server;  this 
machine-readable  file  serves  as  a color  name  database,  and  is  discussed  more  fully  in  Appen- 
dix A,  System  Management.  The  rgb.txt  file  is  the  human-readable  equivalent. 
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The  default  rgb.txt  file  shipped  with  Release  4 of  X contains  738  color  name  definitions. 
This  number  is  slightly  deceptive,  since  as  we’ve  said,  a number  of  the  color  names  are 
merely  variants  of  another  color  name  (differing  only  in  spelling,  spacing  and  capitalization). 

Still,  the  number  of  colors  available  in  Release  4 is  more  than  double  the  number  available  in 
Release  3.  Some  of  the  Release  4 colors  are  entirely  new  (like  snow  and  misty  rose),  but 
many  are  just  slightly  different  shades  of  colors  available  in  prior  releases. 

For  example,  the  Release  3 rgb.txt  file  includes  the  color  sea  green.  The  Release  4 rgb.txt  file 
offers  the  following  shades  of  that  color: 

light  sea  green 

sea  green 

medium  sea  green 

dark  sea  green 

SeaGreenl 

SeaGreen2 

SeaGreer.3 

SeaGreen4 

Dark SeaGreenl 

DarkSeaGreen2 

DarkSeaGreen3 

DarkSeaGreen4 

Each  of  these  names  corresponds  to  a color  definition.  (This  list  does  not  include  the  variants 
SeaGreen,  LightSeaGreen,  MediumSeaGreen,  and  DarkSeaGreen,  which  also  appear  in  the 
file.)  As  you  can  see,  some  of  these  shades  are  distinguished  in  the  fairly  traditional  way  of 
being  called  “light,”  “medium,”  and  “dark.”  The  light,  medium,  and  dark  shades  of  a color 
can  probably  be  distinguished  from  one  another  on  virtually  any  monitor. 

Beyond  this  distinction,  there  are  what  might  be  termed  “sub-shades;”  gradations  of  a partic- 
ular shade  identified  by  number  (SeaGreenl,  SeaGreen2,  etc.).  Numerically  adjacent  sub- 
shades of  a color  may  not  be  clearly  distinguishable  on  all  monitors.  For  example,  Sea- 
Greenl and  2 may  look  very  much  the  same.  (You  certainly  would  not  choose  to  create  a 
window  with  a SeaGreenl  background  and  SeaGreen2  foreground!  On  the  other  hand,  sub- 
shades a couple  of  numbers  apart  are  probably  sufficiently  different  to  be  used  on  the  same 
window.) 

By  supplying  many  different  shades  of  a single,  already  fairly  precise  color  like  sea  green,  X 
developers  have  tried  to  provide  definitions  that  work  well  on  a variety  of  commonly-used 
monitors.*  You  may  have  to  experiment  to  determine  which  colors  (or  shades)  display  best 
on  your  monitor. 

The  color  names  in  the  Release  4 rgb.txt  file  are  too  numerous  to  list  here.  Although  there 
are  no  literal  dividers  within  the  file,  it  can  roughly  be  considered  to  fall  into  three  sections: 


♦The  color  database  shipped  with  prior  releases  of  X was  originally  designed  to  display  optimally  on  the  vt240  series 
terminals  manufactured  by  Digital  Equipment  Corporation. 
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Section  1: 


Section  2: 
Section  3: 


A standard  spectrum  of  colors,  many  available  in  or  similar  to  colors  in 
Release  3 (such  as  sea  green).  These  colors  seem  to  be  ordered  roughly 
as  follows,  off-whites  and  other  pale  colors,  greys,  blues,  greens,  yel- 
lows, browns,  oranges,  pinks,  reds,  and  purples. 

Sub-shades  of  Section  1 colors  (such  as  SeaGreen  1 through  4).  These 
sub-shades  comprise  the  largest  part  of  the  file. 

One  hundred  and  one  additional  shades  of  grey,  numbered  0 through 
100  (also  available  in  Release  3).  This  large  number  of  precisely  gradu- 
ated greys  provides  a wide  variety  of  shading  for  monochrome  screens. 


Rather  than  list  every  color  in  the  rgb.txt  file,  we’ve  compiled  the  following  table  of  repre- 
sentative colors.  We  ve  chosen  some  of  the  more  esoteric  color  names.  Naturally,  all  of  the 
primary  and  secondary  colors  are  available  also. 


Section  1: 


ghost  white 
slate  grey 
dodger  blue 
lawn  green 
khaki 

sienna 

tomato 

magenta 

peach  puff 
midnight  blue 
powder  blue 
chartreuse 
light  yellow 
sandy  brown 
hot  pink 
medium  orchid 

lavendar  blush 
cornflower  blue 
turquoise 
olive  drab 
goldenrod 
salmon 

maroon 

blue  violet 

lemon  chiffon 
medium  slate  blue 
pale  green 
lime  green 
indian  red 
coral 

violet  red 
purple 

Section  2: 

snowl  - 4 

azurel  - 4 
PaleTurquoi sel  - 4 
SpringGreenl  -4 
chocolatel  - 4 
DeepPinkl  - 4 

bisquel  - 4 
SteelBluel  - 4 
aquamarinel  - 4 
goldl  - 4 
firebrickl  - 4 
PaleVioletRedl  - 4 

cornsilkl  - 4 
DeepSkyBluel  - 4 
PaleGreenl  - 4 
RosyBrownl  - 4 
DarkOrangel  - 4 
pluml  - 4 

honeydewl  -4 
LightCyanl  - 4 
DarkOl iveGreenl  - 
burlywoodl  - 4 
OrangeRedl  - 4 
DarkOrchidl  - 4 

Section  3: 


greyO  (grayO)  through  greylOO  (graylOO) 

If  you  want  to  look  more  closely  at  the  rgb.txt  file,  you  can  open  it  with  any  text  editor.  As 
an  alternative,  you  can  also  display  the  contents  of  the  file  using  the  showrgb  client,  showrgb 
seems  to  do  nothing  more  than  cat(  1)  the  file  to  your  terminal  window.  Given  the  size  of  the 
file,  it’s  necessary  to  pipe  the  command’s  output  to  a paging  program,  such  as  pg(  1)  or 
more(  1). 

% showrgb  | more 

See  Appendix  A,  System  Management,  for  information  on  customizing  color  name 
definitions. 
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The  following  are  the  default  color  names  shipped  with  Release  3 of  the 
Again,  this  list  does  not  include  the  many  variants  of  these  names. 


aquamarine 
cadet  blue 
light  steel  blue 
navy  blue 
steel  blue 
brown 

medium  goldenrod 

forest  green 

medium  spring  green 

yellow  green 

light  grey 

orange 

pink 

medium  violet  red 
sienna 

dark  turquoise 
wheat 


medium  aquamarine 
corn  flowerblue 
medium  blue 
navy 
coral 

sandy  brown 
green 

lime  green 

pale  green 

dark  slate  grey 

khaki 

orchid 

plum 

orange  red 
tan 

medium  turquoise 
white 


black 

dark  slate  blue 

medium  slate  blue 

sky  blue 

cyan 

gold 

dark  green 

medium  forest  green 

sea  green 

grey 

magenta 

dark  orchid 

red 

violet  red 
thistle 
violet 
yellow 


X Window  System. 

blue 

light  blue 
midnight  blue 
slate  blue 
firebrick 
goldenrod 
dark  olive  green 
medium  sea  green 
spring  green 
dim  grey 
maroon 

medium  orchid 
indian  red 
salmon 
turquoise 
blue  violet 
green  yellow 


greyO  (grayO)  through  greylOO  (graylOO) 


Alternative  Release  4 Color  Databases 


In  addition  to  the  standard  color  database  described  above,  Release  4 also  includes  three 
other  databases  that  can  be  compiled  by  your  system  administrator.  These  files  can  be  found 
in  the  general  release  in  the  directory  .Irgblothers. 


raveling.txt 


thomas.txt 


old-rgb.txt 


Designed  by  Paul  Raveling,  this  database  rivals  the  default  database  in 
size  and  scope,  but  has  been  tuned  to  display  optimally  on  Hewlett- 
Packard  monitors. 

Based  on  the  Release  3 database,  this  file  has  been  modified  by  John 
Thomas  of  Tektronix  to  approximate  the  colors  in  a box  of  Crayola 
Crayons. 

This  is  nothing  more  than  the  Release  3 database. 


Hexadecimal  Color  Specification 

You  can  also  specify  colors  more  exactly  using  a hexadecimal  color  string.  You  probably 
won’t  use  this  method  unless  you  require  a color  not  available  by  using  a color  name.  In 
order  to  understand  how  this  works,  you  may  need  a little  background  on  how  color  is  imple- 
mented on  most  workstations. 
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The  RGB  Color  Model 


Most  color  displays  on  the  market  today  are  based  on  the  RGB  color  model.  Each  pixel  on 
the  screen  is  actually  made  up  of  three  phosphors:  one  red,  one  green,  and  one  blue.  Each  of 
these  three  phosphors  is  excited  by  a separate  electron  beam.  When  all  three  phosphors  are 
fully  illuminated,  the  pixel  appears  white  to  the  human  eye.  When  all  three  are  dark,  the 
pixel  appears  black.  When  the  illumination  of  each  primary  color  varies,  the  three  phosphors 
generate  a subtractive  color.  For  example,  equal  portions  of  red  and  green,  with  no  admix- 
ture of  blue,  makes  yellow. 

As  you  might  guess,  the  intensity  of  each  primary  color  is  controlled  by  a three-part  digital 
value — and  it  is  the  exact  makeup  of  this  value  that  the  hexadecimal  specification  allows  you 
to  set. 


Depending  on  the  underlying  hardware,  different  servers  may  use  a larger  or  smaller  number 
of  bits  (from  4 to  16  bits)  to  describe  the  intensity  of  each  primary.  To  insulate  you  from  this 
variation,  most  clients  are  designed  to  take  color  values  containing  anywhere  from  4 to  16 
bits  (1  to  4 hex  digits),  and  the  server  then  scales  them  to  the  hardware.  As  a result,  you  can 
specify  hexadecimal  values  in  any  one  of  the  following  formats: 

#RGB 

#RRGGBB 

#RRRGGGBBB 

tRRRRGGGGBBBB 


where  R,  G,  and  B represent  single  hexadecimal  digits  and  determine  the  intensity  of  the  red, 
green,  and  blue  primaries  that  make  up  each  color. 

When  fewer  than  four  digits  are  used,  they  represent  the  most  significant  bits  of  the  value. 
For  example,  #3a6  is  the  same  as  #3000a0006000.* 

What  this  means  concretely  is  perhaps  best  illustrated  by  looking  at  the  values  that  corre- 
spond to  some  colors  in  the  color  name  database.  We’ll  use  8-bit  values — two  hexadecimal 
digits  for  each  primary.  The  following  definitions  are  the  hexadecimal  equivalents  of  the 
decimal  values  for  some  of  the  colors  found  in  the  rgb.txt  file: 


#000000 

tFFFFFF 

#FF0000 

# 00FF00 
#0000FF 
#FFFF00 
#00FFFF 
#FF00FF 

# 5F9EA0 
#64  95ED 
#ADD8E6 
#B0C4  DE 
#0000CD 
#000080 


black 

white 

red 

green 

blue 

yellow 

cyan 

magenta 

cadet  blue 

cornflower  blue 

light  blue 

light  steel  blue 

medium  blue 

navy  blue 


•If  you  are  unfamiliar  with  hexadecimal  numbering,  see  the  Glossary  for  a brief  explanation,  or  a basic  compute, 
textbook  for  a more  extended  discussion. 
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#87CEED 
#6A5ACE 
#4  682B4 


sky  blue 
slate  blue 
steel  blue 


As  you  can  see  from  the  colors  given  above,  pure  red,  green,  and  blue  result  from  the  corre- 
sponding bits  being  turned  full  on.  All  primaries  off  yields  black,  while  all  nearly  full  on 
gives  white.  Yellow,  cyan,  and  magenta  can  be  created  by  pairing  two  of  the  other  primaries 
at  full  intensity.  The  various  shades  of  blue  shown  above  are  created  by  varying  the  intensity 
of  each  primary — sometimes  in  unexpected  ways. 

The  bottom  line  here  is  that  if  you  don’t  intimately  know  the  physics  of  color,  the  best  you 
can  do  is  to  look  up  existing  colors  from  the  color  name  database  and  experiment  with  them 
by  varying  one  or  more  of  the  primaries  till  you  find  a color  you  like.  Unless  you  need  pre- 
cise colors,  you  are  probably  better  off  using  color  names. 

How  Many  Colors  are  Available? 

The  number  of  distinct  colors  available  on  the  screen  at  any  one  time  depends  on  the  amount 
of  memory  available  for  color  specification.  (The  xdpyinfo  client  provides  information  about 
a display,  including  the  number  of  colors  available  at  one  time.  See  Chapter  7,  Other  Clients, 
and  the  xdpyinfo  reference  page  in  Part  Three  for  details.) 

A color  display  uses  multiple  bits  per  pixel  (also  referred  to  as  multiple  planes  or  the  depth  of 
the  display)  to  select  colors.  Programs  that  draw  in  color  use  the  value  of  these  bits  as  a 
pointer  to  a lookup  table  called  a colormap,  in  which  each  entry  (or  colorcell)  contains  the 
RGB  values  for  a particular  color.*  As  shown  in  Figure  8-2,  any  given  pixel  value  is  used  as 
an  index  into  this  table — for  example,  a pixel  value  of  16  will  select  the  sixteenth  colorcell. 

Why  is  this  technical  detail  important?  Because  it  explains  several  issues  that  you  might 
encounter  in  working  with  color  displays. 

First,  the  range  of  colors  possible  on  the  display  is  a function  of  the  number  of  bits  available 
in  the  colormap  for  RGB  specification.  If  eight  bits  is  available  for  each  primary,  then  the 
range  of  possible  colors  is  256 3 (somewhere  over  16  million  colors).  This  means  that  you 
can  create  incredibly  precise  differences  between  colors. 

However,  the  number  of  different  colors  that  can  be  displayed  on  the  screen  at  any  one  time 
is  a function  of  the  number  of  planes.  A four-plane  system  can  index  2 4 colorcells  (16  dis- 
tinct colors);  an  eight-plane  system  can  index  2 8 colorcells  (256  distinct  colors);  and  a 
24-plane  system  can  index  2 24  colorcells  (over  16  million  distinct  colors). 

If  you  are  using  a four-plane  workstation,  the  fact  that  you  can  precisely  define  hundreds  of 
different  shades  of  blue  is  far  less  significant  than  the  fact  that  you  can’t  use  them  all  at  the 
same  time.  There  isn’t  space  for  all  of  them  to  be  stored  in  the  colormap  at  one  time,  or  any 
mechanism  for  them  to  be  selected  even  if  they  could  be  stored. 


* There  is  a type  of  high-end  display  in  which  pixel  values  are  used  directly  to  control  the  illumination  of  the  red, 
green,  and  blue  phosphors,  but  far  more  commonly,  the  bits  per  pixel  are  used  indirectly,  with  the  actual  color  values 
specified  independently,  as  described  here. 
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Frame 

Buffer 


Colormap 

RGB 


Figure  8-2.  Multiple  planes  used  to  index  a colormap 

This  limitation  is  made  more  significant  by  the  fact  that  X is  a multi-client  environment. 
When  X starts  up,  usually  no  colors  are  loaded  into  the  colormap.  As  clients  are  invoked, 
certain  of  these  cells  are  allocated.  But  when  all  of  the  free  colorcells  are  used  up,  it  is  no 
longer  possible  to  request  new  colors.  When  this  happens,  you  will  usually  be  given  the 
closest  possible  color  from  those  that  have  already  been  allocated.  However,  you  may 
instead  be  given  an  error  message  and  told  that  there  are  no  free  colorcells. 

In  order  to  minimize  the  chance  of  running  out  of  colorcells,  many  programs  use  “shared” 
colorcells.  Shared  colorcells  can  be  used  by  any  number  of  applications,  but  they  can’t  be 
changed  by  any  of  them.  They  can  only  be  deallocated  by  each  application  that  uses  them, 
and  when  all  applications  have  deallocated  the  cell,  it  is  available  for  setting  one  again. 
Shared  cells  are  most  often  used  for  background,  border,  and  cursor  colors. 

Alternately,  some  clients  have  to  be  able  to  change  the  color  of  graphics  they  have  already 
drawn.  This  requires  another  kind  of  cell,  called  private,  which  can’t  be  shared.  A typical 
use  of  a private  cell  would  be  for  the  pallete  of  a color  mixing  application.  Such  a program 
might  have  three  bars  of  each  primary  color,  and  a box  which  shows  the  mixed  color.  The 
primary  bars  would  use  shared  cells,  while  the  mixed  color  box  would  use  a private  cell. 

In  summary,  some  programs  define  colorcells  to  be  read-only  and  shareable,  while  others 
define  colorcells  to  be  read/write  and  private. 

To  top  it  off,  there  are  even  clients  that  may  temporarily  swap  in  a whole  private  colormap  of 
their  own.  Because  of  the  way  color  is  implemented,  if  this  happens,  all  other  applications 
will  be  displayed  in  unexpected  colors. 
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In  order  to  minimize  such  conflicts,  you  should  request  precise  colors  only  when  necessary. 
By  preference,  use  color  names  or  hexadecimal  specifications  that  you  specified  for  other 
applications. 


Starting  a Client  Window  as  an  Icon 

The  -iconic  command  line  option  starts  the  client  window  in  iconified  form.  To  start  an 
xterm  window  as  an  icon,  type: 

% xterm  -iconic  & 

This  can  be  especially  useful  for  starting  the  login  x term  window.  As  described  in  Chapter  2, 
Getting  Started,  terminating  the  login  xterm  window  kills  the  X server  and  all  other  clients 
that  are  running.  It’s  always  possible  to  terminate  a window  inadvertently,  by  selecting  the 
wrong  menu  option  or  typing  the  wrong  key  sequence.  If  your  login  xterm  window  is  auto- 
matically iconified  at  startup,  you  are  far  less  likely  to  terminate  the  window  inadvertently 
and  end  your  X session. 

For  most  clients,  the  size  and  position  of  the  icon  can  be  set  using  resource  variables  in  an 
Xdefaults  or  other  resource  file.  (This  is  highly  recommended  if  you  are  starting  the  login 
xterm  window  as  an  icon.)  See  the  appropriate  client  reference  pages  in  Part  Three  for  a 
complete  list  of  available  resources.  Refer  to  Chapter  9,  Setting  Resources,  for  instructions 
on  how  to  set  resources. 


Specifying  Fonts  on  the  Command  Line 

Many  clients  allow  you  to  specify  the  font  to  be  used  when  displaying  text  in  the  window. 
(These  are  known  as  screen  fonts  and  are  not  to  be  confused  with  printer  fonts.)  For  clients 
written  with  the  X Toolkit,  the  option  to  set  the  display  font  is  -f  n.  For  example,  the  com- 
mand line: 

% xterm  -fn  fontname  t 

creates  an  xterm  window  in  which  text  will  be  displayed  with  the  font  named  fontname. 

Chapter  5,  Font  Specification,  describes  the  available  screen  fonts  and  font  naming 
conventions. 
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Reverse  Video 


There  are  three  options  to  control  whether  or  not  the  application  will  display  in  reverse 
video — that  is,  with  the  foreground  and  background  colors  reversed.  The  -rv  or 
-reverse  option  is  used  to  request  reverse  video. 

The  +rv  option  is  used  to  override  any  reverse  video  request  that  might  be  specified  in  a 
resource  file  (see  Chapter  9,  Setting  Resources).  This  is  important,  because  not  all  clients 
handle  reverse  video  correctly,  and  even  those  that  do  usually  do  so  only  on  black  and  white 
displays. 
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This  chapter  describes  how  to  set  resource  variables  that  determine  applica- 
tion features  such  as  color,  geometry,  fonts,  and  so  on.  It  describes  the  syn- 
tax of  resource  definition  files  such  as  .Xresources,  as  well  as  the  operation 
ofxr db,  a client  that  can  be  used  to  change  resource  definitions  dynamically, 
and  make  resources  available  to  clients  running  on  other  machines. 

In  This  Chapter: 


Resource  Naming  Syntax  182 

Syntax  of  Toolkit  Client  Resources 183 

Tight  Bindings  and  Loose  Bindings  184 

Instances  and  Classes 184 

Precedence  Rules  for  Resource  Specification 185 

Some  Common  Resources 187 

Event  Translations  188 

The  Syntax  of  Event  Translations 189 

xterm  Translations  to  Use  xclipboard 191 

Howto  Set  Resources  192 

A Sample  Resources  File 193 

Specifying  Resources  from  the  Command  Line 194 

The  -xrm  Option 194 

The -name  Option 194 

Setting  Resources  with  xrdb  195 

Querying  the  Resource  Database  196 

Loading  New  Values  into  the  Resource  Database  196 

Saving  Active  Resource  Definitions  in  a File 197 

Removing  Resource  Definitions  197 

Listing  the  Current  Resources  for  a Client:  appres  198 

Other  Sources  of  Resource  Definition  199 
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Virtually  all  X clients  are  customizable.  You  can  specify  how  a client  looks  on  the  screen— 
its  size  and  placement,  its  border  and  background  color  or  pattern,  whether  or  not  the  window 
has  a scrollbar,  and  so  on.  Some  applications  even  allow  you  to  redefine  the  keystrokes  or 
pointer  actions  used  to  control  the  application. 

Traditional  UNIX  applications  rely  on  command  line  options  to  allow  users  to  customize  the 
way  they  work.  As  we’ve  already  discussed  in  Chapter  8,  Command  Line  Options , X appli- 
cations support  command  line  options  too,  but  often  not  for  all  of  their  features.  Also,  there 
can  be  so  many  customizable  features  in  an  application  that  a command  line  to  set  them  all 
would  be  completely  impractical.  (Imagine  the  aggravation  of  misspelling  an  option  in  a 
command  that  was  three  lines  long.) 

X offers  an  alternative  to  customizing  an  application  on  the  command  line.  Almost  every 
feature  of  a program  can  be  controlled  by  a variable  called  a resource ; you  can  change  the 
behavior  or  appearance  of  a program  by  changing  the  value  associated  with  a resource  vari- 
able. (All  of  the  standard  X Toolkit  Command  Line  Options  described  in  Chapter  8 have  cor- 
responding resource  variable  names.  See  Table  8-1  for  more  information.) 

Resource  variables  may  be  Boolean  (such  as  scrollBar:  True)  or  take  a numeric  or 
string  value  (borderWidth : 2 or  foreground:  blue).  What’s  more,  in  applica- 
tions written  with  the  X Toolkit  (or  other  object-oriented  systems),  resources  may  be  associ- 
ated with  separate  objects  (or  “widgets”)  within  an  application.  There  is  a syntax  that  allows 
for  separate  control  over  both  a class  of  objects  in  the  application  and  an  individual  instance 
of  an  object.  This  is  illustrated  by  the  following  resource  specifications  for  a hypothetical 
application  called  xclient: 

xclient *Buttons . foreground:  blue 

xclient *help . foreground:  red 

The  first  resource  specification  makes  the  foreground  color  of  all  buttons  in  the  xclient  appli- 
cation (in  the  class  Buttons)  blue;  the  second  resource  specification  makes  the  foreground 
color  of  the  help  button  in  this  application  (an  instance  of  the  class  Buttons)  red. 

The  values  of  resources  can  be  set  as  application  defaults  using  a number  of  different  mecha- 
nisms, including  resource  files  in  your  home  directory  and  a program  called  xrdb  (X  resource 
database  manager).  As  we’ll  see,  the  xrdb  program  stores  resources  directly  in  the  server, 
thus  making  them  available  to  all  clients,  regardless  of  the  machine  the  clients  are  running 
on. 
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Placing  resources  in  files  allows  you  to  set  many  resources  at  once,  without  the  restrictions 
encountered  when  using  command  line  options.  In  addition  to  a primary  resource  file  (often 
called  Xdefauhs  or  X resources ) in  your  home  directory,  which  determines  defaults  for  appli- 
cations you  run,  you  can  create  system -wide  resource  files  to  set  application  defaults.  You 
can  also  create  resource  files  to  set  some  resources  only  for  the  local  machine,  some  for  all 
machines  in  a network,  and  some  for  one  or  more  specific  machines. 

The  various  resource  files  are  automatically  read  in  and  processed  in  a certain  order  within 
an  application  by  a set  of  routines  called  the  resource  manager.  The  syntax  for  resource 
specifications  and  the  rules  of  precedence  by  which  the  resource  manager  processes  them  are 
intended  to  give  you  the  maximum  flexibility  in  setting  resources,  with  the  minimum  amount 
of  text.  You  can  specify  a resource  that  controls  only  one  feature  of  a single  application, 
such  as  the  red  help  button  in  the  hypothetical  xclient  settings  above.  You  can  also  specify 
a resource  that  controls  one  feature  of  multiple  objects  within  multiple  applications  with  a 
single  line. 

It  is  important  to  note  that  command  line  options  normally  take  precedence  over  any  prior 
resource  settings,  so  you  can  set  up  the  files  to  control  the  way  you  normally  want  your  appli- 
cation to  work,  and  then  use  command  line  options  to  specify  changes  you  need  for  only  one 
or  two  instances  of  the  application. 

In  this  chapter,  we’ll  first  look  at  the  syntax  of  resource  specifications.  Then  we’ll  consider 
some  methods  of  setting  resources,  primarily  some  special  command  line  options  and  the 
xrdb  program.  Finally,  we’ll  take  a brief  look  at  the  section  “Other  Sources  of  Resource  Def- 
inition,” additional  files  that  can  be  created  or  edited  to  set  application  resources. 


Resource  Naming  Syntax 

The  basic  syntax  of  a resource  definition  file  is  fairly  simple.  Each  client  recognizes  certain 
resource  variables  that  can  be  assigned  a value.  The  variables  for  each  client  are  documented 
on  its  reference  page  in  Part  Three  of  this  guide. 

Most  of  the  common  clients  are  written  to  use  the  X Toolkit.  As  described  in  Chapter  7, 
Other  Clients , toolkits  are  a mechanism  for  simplifying  the  design  and  coding  of  applica- 
tions, and  making  them  operate  in  a consistent  way.  Toolkits  provide  a standard  set  of 
objects,  or  “widgets,”  such  as  menus,  command  buttons,  dialog  boxes,  scrollbars,  and  so  on. 
As  we’ll  see,  the  naming  syntax  for  certain  resources  parallels  the  object  hierarchy  that  is 
built  into  X Toolkit  programs.* 

The  most  basic  line  you  can  have  in  a resource  definition  file  consists  of  the  name  of  a client, 
followed  by  a period  or  an  asterisk  and  the  name  of  a variable.  A colon  and  whitespace  sepa- 


*If  a client  was  built  with  the  X Toolkit,  this  should  be  noted  on  the  reference  page.  In  addition  to  certain  applica- 
tion-specific resource  variables,  clients  that  use  the  X Toolkit  have  a common  set  of  resource  variables.  These  com- 
mon variables  may  not  be  shown  on  each  reference  page,  but  all  of  the  Toolkit  variables  are  listed  in  Table  8-1,  in 
Chapter  8,  Command  Line  Options  and  are  described  in  slightly  greater  detail  on  the  X reference  page  in  Part  Three 
of  this  guide.  A few  of  the  more  common  variables  also  appear  in  Table  9-1  later  in  this  chapter. 


182 


X Window  System  User's  Guide 


rate  the  client  and  variable  names  from  the  actual  value  of  the  resource  variable.  The  follow- 
ing line  specifies  that  all  instances  of  the  xterm  application  have  a scrollbar: 

xterm*scrollBar : True 

If  the  name  of  the  client  is  omitted,  the  variable  applies  to  all  instances  of  all  clients  (in  this 
case,  all  clients  that  can  have  a scrollbar).  If  the  same  variable  is  specified  as  a global  vari- 
able and  a client-specific  variable,  the  value  of  the  client-specific  variable  takes  precedence 
for  that  client.  Note,  however,  that  if  the  name  of  the  client  is  omitted,  the  line  should  gener- 
ally begin  with  an  asterisk. 

Be  sure  that  you  don’t  inadvertently  omit  the  colon  at  the  end  of  a resource  specification. 
This  is  an  easy  mistake  to  make  and  the  resource  manager  provides  no  error  messages.  If 
there  is  an  error  in  a resource  specification  (including  a syntax  error  like  the  omission  of  the 
colon  or  a misspelling),  the  specification  is  ignored.  The  value  you  set  will  simply  not  take 
effect.  To  include  a comment  in  a resource  file  or  comment  out  one  of  the  resource  specifica- 
tions, begin  the  line  in  question  with  an  exclamation  point  (!).  If  the  last  character  on  a line 
is  a backslash  (\),  the  resource  definition  on  that  line  is  assumed  to  continue  on  the  next  line. 


Syntax  of  Toolkit  Client  Resources 


As  mentioned  above,  X Toolkit  applications  are  made  up  of  predefined  components  called 
widgets.  There  can  be  widgets  within  widgets  (e.g.,  a command  button  within  a dialog  box). 
The  syntax  of  resource  specifications  for  Toolkit  clients  parallels  the  levels  of  the  widget 
hierarchy.  Accordingly,  you  should  think  of  a resource  specification  as  having  the  following 
format: 

object . subobject[.  subobject . . .] . attr ibute:  value 


where: 

is  the  client  program,  or  a specific  instance  of  the  program.  (See  The 
-name  Option  later  in  this  chapter.) 

correspond  to  levels  of  the  widget  hierarchy  (usually  the  major  structures 
within  an  application,  such  as  windows,  menus,  scrollbars,  etc.). 

is  a feature  of  the  last  subobject  (perhaps,  a command  button),  such  as 
background  color  or  a label  that  appears  on  it. 

is  the  actual  setting  of  the  resource  attribute,  i.e.,  the  label  text,  color, 
or  other  feature. 

The  type  of  value  to  supply  should  usually  be  evident  from  the  name  of  the  resource  or 
from  the  description  of  the  resource  variable  on  the  reference  page.  Most  of  these  values  are 
similar  to  those  used  with  the  command  line  options  described  in  Chapter  8,  Command  Line 
Options. 

For  example,  various  resources,  such  as  borderColor  or  background,  take  color  spec- 
ifications; geometry  takes  a geometry  string,  font  takes  a font  name,  and  so  on.  Logical 
values,  such  as  the  values  taken  by  scrollBar,  can  be  generally  specified  as  on  or  off, 
as  yes  or  no,  or  as  True  or  False. 


object 

subobjects 

attribute 

value 
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Tight  Bindings  and  Loose  Bindings 


Binding  refers  to  the  way  in  which  components  of  a resource  specification  are  linked 
together.  Resource  components  can  be  linked  in  two  ways: 

• By  a tight  binding,  represented  by  a dot  (.). 

• By  a loose  binding,  represented  by  an  asterisk  (*). 

A tight  binding  means  that  the  components  on  either  side  of  the  dot  must  be  next  to  one 
another  in  the  widget  hierarchy.  A loose  binding  is  signalled  by  an  asterisk,  a wildcard  char- 
acter, which  means  there  can  be  any  number  of  levels  in  the  hierarchy  between  the  two  sur- 
rounding components. 

If  you  want  to  specify  tight  bindings,  you  must  be  very  familiar  with  the  widget  hierarchy. 
It’s  easy  to  use  tight  bindings  incorrectly. 

For  example,  the  following  resource  specification  to  request  that  xterm  windows  be  created 
with  a scrollbar  doesn’t  work: 

xterm. scrollBar : True 

This  specification  ignores  the  widget  hierarchy  of  xterm , in  which  the  VT102  window  is  con- 
sidered to  be  one  widget,  the  Tektronix  window  another,  and  the  menus  a third.  This  means 
that  if  you  want  to  use  tight  bindings  to  request  that  xterm  windows  be  created  with  a 
scrollbar,  you  should  specify: 

xterm . vt 100 . scrollBar : True 

Of  course,  rather  than  decipher  the  widget  hierarchy  (which  may  even  change  with  subse- 
quent versions  of  an  application),  it  is  far  simpler  just  to  use  the  asterisk  connector  in  the  first 

place: 

xterm*scrollBar : True 

In  an  application  that  supports  multiple  levels  of  widgets,  you  can  mix  asterisks  and  periods. 
In  general,  though,  the  developers  of  X recommend  always  using  the  asterisk  rather  than  the 
dot  as  the  connector  even  with  simple  applications,  since  this  gives  application  developers 
the  freedom  to  insert  new  levels  in  the  hierarchy  as  they  produce  new  releases  of  an  applica- 
tion. 


Instances  and  Classes 

Each  component  of  a resource  specification  has  an  associated  class.  Several  different  widg- 
ets, or  widget  attributes,  may  have  the  same  class.  For  example,  in  the  case  of  xterm , the 
color  of  text  (foreground),  the  pointer  color,  and  the  text  cursor  color  are  all  defined  as 
instances  of  the  class  Foreground.  This  makes  it  possible  to  set  the  value  of  all  three  with 
a single  resource  specification.  That  is,  if  you  wanted  to  make  the  text,  the  pointer,  and  the 
cursor  dark  blue,  you  could  specify  either: 
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or: 


xterm*foreground:  darkblue 
xterm*cursorColor : darkblue 
xterm*pointerColor : darkblue 


xterm*Foreground : darkblue 

Initial  capitalization  is  used  to  distinguish  class  names  from  instance  names.  Class  names 
always  begin  with  an  uppercase  letter,  while  instance  names  always  begin  with  a lowercase 
letter.  Note  however  that  if  an  instance  name  is  a compound  word  (such  as  cursor- 
Color),  the  second  word  is  usually  capitalized. 

The  real  power  of  class  and  instance  naming  is  not  apparent  in  applications  like  xterm  that 
have  a simple  widget  hierarchy.  In  complex  applications  written  with  the  X Toolkit,  class 
and  instance  naming  allows  you  to  do  such  things  as  specify  that  all  buttons  in  dialog  box  be 
blue,  but  that  one  particular  button  be  red.  For  example,  in  the  hypothetical  xclient  applica- 
tion, you  might  have  a resource  file  that  reads: 

xclient *buttonbox* But tons ‘foreground : blue 
xclient *buttonbox* delete* foreground : red 

where  Buttons  is  a class  name  and  the  delete  button  is  an  instance  of  the  Buttons 
class.  This  type  of  specification  works  because  an  instance  name  always  overrides  the  corre- 
sponding class  name,  for  that  instance.  Class  names  thus  allow  default  values  to  be  specified 
for  all  instances  of  a given  type  of  object.  Instance  names  can  be  used  to  specify  exceptions 
to  the  rules  outlined  by  the  class  names.  Note  that  a class  name  can  be  used  with  a loose 
binding  to  specify  a resource  for  all  clients.  For  example,  the  following  specification  would 
say  that  the  foreground  colors  for  all  clients  should  be  blue: 

♦Foreground:  blue 

The  reference  page  for  a given  program  should  always  give  you  both  instance  and  class 
names  for  every  resource  variable  you  can  set.  You’ll  notice  that  in  many  cases,  the  class 
name  is  identical  to  the  instance  name,  with  the  exception  of  the  initial  capital  letter.  Often 
(but  not  always)  this  means  that  there  is  only  one  instance  of  that  class.  In  other  cases,  the 
instance  with  the  same  name  is  simply  the  primary  or  most  obvious  instance  of  the  class. 


Precedence  Rules  for  Resource  Specification 

Even  within  a single  resource  file,  such  as  X resources , resource  specifications  often  conflict. 
For  instance,  recall  the  example  from  the  first  page  of  the  chapter,  involving  the  hypothetical 
xclient  application: 

xclient *Buttons . foreground : blue 

xclient *help . foreground : red 

The  first  resource  specification  makes  the  foreground  color  of  all  buttons  (in  the  class  But- 
tons) blue.  The  second  resource  specification  overrides  the  first  in  one  instance:  it  makes 
the  foreground  color  of  the  help  button  (an  instance  of  the  class  Buttons)  red.  In  the 
event  of  conflicting  specifications,  there  are  a number  of  rules  that  the  resource  manager  fol- 
lows in  deciding  which  resource  specification  should  take  effect. 
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We’ve  already  seen  two  of  these  rules,  which  are  observable  in  the  way  the  resource  manager 
interprets  definitions  in  a user-created  resource  file.  (The  first  rule  applies  in  the  xclient 
example  above.) 

• Instance  names  take  precedence  over  class  names. 

• Tight  bindings  take  precedence  over  loose  bindings. 

From  just  these  two  rules,  we  can  deduce  a general  principle:  the  more  specific  a resource 
definition  is,  the  more  likely  it  is  to  be  honored  in  the  case  of  a conflict. 

However,  for  cases  in  which  you  want  to  set  things  up  very  carefully,  you  should  know  a bit 
about  how  programs  interpret  resource  specifications. 

For  each  resource,  the  program  has  both  a complete,  fully-specified,  tightly-bound  instance 
name  and  class  name.  In  evaluating  ambiguous  specifications,  the  program  compares  the 
specification  against  both  the  full  instance  name  and  the  full  class  name.  If  a component  in 
the  resource  specification  matches  either  name,  it  is  accepted.  If  it  matches  more  than  one 
element  in  either  name,  it  is  evaluated  according  to  the  following  precedence  rules: 

1.  The  levels  in  the  hierarchy  specified  by  the  user  must  match  the  program’s  expecta- 
tions, or  the  entry  will  be  ignored.  For  example,  if  the  program  expects  either  of  the 
following: 

xterm.  vt  10  0 . scrollBar  : value  instance  name 

XTerm.  VT100  . ScrollBar  : value  class  name 

the  resource  specification: 

xterm. scrollBar : True 

won’t  work,  because  the  tight  binding  is  incorrect.  The  objects  xterm  and  scroll- 
Bar are  not  adjacent  in  the  widget  hierarchy.  There  is  another  widget,  vtlOO, 
between  them.  The  specification  would  work  if  you  used  a loose  binding,  however: 

xterm*scrollBar : True 

(Note  that  the  class  name  of  xterm  is  XTerm,  not  xterm  as  you  might  expect.) 

2.  Tight  bindings  take  precedence  over  loose  bindings.  That  is,  entries  with  instance  or 
class  names  prefixed  by  a dot  are  more  specific  than  entries  with  names  prefixed  by  an 
asterisk,  and  more  specific  entries  take  precedence.  For  example,  the  entry 
xterm. vtlOO  .geometry  will  take  precedence  over  the  entry  xterm*geome- 
try. 

3.  Similarly,  instances  take  precedence  over  classes.  For  example,  the  entry  ♦scroll- 
Bar will  take  precedence  over  the  entry  * Scrollbar. 

4.  An  instance  or  class  name  that  is  explicitly  stated  takes  precedence  over  one  that  is 
omitted.  For  example,  the  entry  xterm*scrollbar  is  more  specific  than  the  entry 
♦scrollBar. 

5.  Left  components  carry  more  weight  than  right  components.  For  example,  the  entry 
xterm*background  will  take  precedence  over  *background. 
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To  illustrate  these  rules,  let  s consider  the  following  resource  specifications  for  the  hypotheti- 
cal Toolkit  application  xclient,  as  shown  in  Example  9-1. 

Example  9-1 . Sample  resources 

xclient . toe* Command . act iveForeground : black 

♦Command . Foreground : green 

The  program  would  try  to  match  these  specifications  against  the  complete  tightly-bound 
instance  and  class  specifications  following: 

xclient. toe.  me  ssageFunct  ions,  include . act  iveForeground  instance  name 

Xclient . Box . SubBox  . Command . Foreground  class  name 

Note  that  these  specifications  are  the  instance  and  class  names  for  the  same  resource.  Each 
component  of  the  instance  name  belongs  to  the  class  in  the  corresponding  component  of  the 
class  name.  Thus,  the  instance  toe  occurs  in  the  class  Box,  the  messageFunctions 
instance  name  is  from  the  class  SubBox,  etc. 

Both  resource  specifications  in  Example  9-1  match  these  instance  and  class  names.  How- 
ever, with  its  tight  bindings  and  instance  names,  xclient . toc*Command . act  ive- 
Foreground matches  more  explicitly;  i.e.,  with  higher  precedence.  That  resource  is  set: 
the  foreground  color  of  the  include  button  in  its  active  state  is  set  to  black. 

The  specification  *Command . Foreground  also  matches  the  instance  and  class  names, 
but  is  composed  entirely  of  class  names  which  are  less  specific.  Thus,  it  takes  lower  prece- 
dence than  the  first  line  in  Example  9-1  (which  sets  the  include  button  to  black). 

However,  since  the  second  line  is  an  acceptable  specification,  hypothetically  it  would  set  the 
foreground  color  of  other  objects  in  the  Command  class.  This  would  be  true  for  xclient,  as 
well  as  any  other  application,  since  the  line  begins  with  the  asterisk  wildcard.  So  if  there 
were  other  xclient  command  buttons  comparable  to  the  include  button  in  the  hierarchy, 
this  second  line  would  set  the  foreground  color  of  these  buttons  to  green.  If  you  want  a 
more  detailed  description  of  how  resource  precedence  works,  see  Section  9.2.3  of  Volume 
Four,  X Toolkit  Intrinsics  Programming  Manual. 


Some  Common  Resources 

Most  applications  written  using  the  X Toolkit  have  a set  of  class  and  instance  names  in  com- 
mon. These  Toolkit  resources  correspond  to  the  Toolkit  options  described  in  Chapter  8,  Com- 
mand Line  Options.  Among  those  Toolkit  resource  variables  you  might  want  to  set  are: 


Table  9-1.  Core  Toolkit  Resources 


Instance  Name 

Class  Name 

Default 

Description 

background 

Background 

White 

Background  color. 

foreground 

Foreground 

Black 

Foreground  color. 

borderColor 

BorderColor 

Black 

Border  color. 
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Note  that  in  a complex  Toolkit  application,  these  values  can  occur  at  every  level  in  a widget 
hierarchy.  For  example,  our  hypothetical  xclient  application  might  support  the  following 
complete  instance  names: 

xclient .background 

xclient . buttonBox . background 

xclient . buttonBox . commandButton . background 

xclient . buttonBox . quit . background 

These  resources  would  specify  the  background  color  for  the  application  window,  the  button 
box  area,  any  command  buttons,  and  the  quit  command  button,  respectively. 

Of  course,  the  specification: 

xclient *background 

would  match  any  and  all  of  them.  See  Table  8-1  for  a comprehensive  list  of  the  common  X 
Toolkit  resources. 


Event  Translations 


We’ve  discussed  the  basics  of  resource  naming  syntax.  From  the  sample  resource  settings,  it 
appears  that  what  many  resource  variables  do  is  self-evident,  or  nearly  so.  Among  the  less 
obvious  resource  variables,  there  is  one  type  of  specification,  an  event  translation,  that  can  be 
used  with  many  clients  and  warrants  somewhat  closer  examination. 

User  input  and  several  other  types  of  information  pass  from  the  server  to  a client  in  the  form 
of  events.  An  event  is  a packet  of  information  that  tells  the  client  something  it  needs  to  act 
on,  such  as  keyboard  input.  As  mentioned  in  Chapter  4,  The  xterm  Terminal  Emulator,  mov- 
ing the  pointer  or  pressing  a key,  etc.,  causes  input  events  to  occur.  When  a program  receives 
a meaningful  event,  it  responds  with  some  sort  of  action. 

For  many  clients,  the  resource  manager  recognizes  mappings  between  certain  input  events 
(like  a pointer  button  click)  and  some  sort  of  action  by  the  client  program  (like  selecting 
text).  A mapping  between  one  or  more  events  and  an  action  is  called  a translation.  A 
resource  containing  a list  of  translations  is  called  a translation  table. 

Many  event  translations  are  programmed  into  an  application  and  are  invisible  to  the  user.* 
For  our  purposes,  we  are  only  concerned  with  very  visible  translations  of  certain  input 
events,  primarily  the  translation  of  keystrokes  and  pointer  button  clicks  to  particular  actions 
by  a client  program. 


♦For  more  information  on  events  and  translations,  see  Volume  Tout,  X Toolkit  Programming  Manual. 
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The  Syntax  of  Event  Translations 


The  operation  of  many  clients,  notably  xterm , is  partly  determined  by  default  input  event 
translations.  For  example,  as  explained  in  Chapter  4,  The  xterm  Terminal  Emulator,  selecting 
text  with  the  first  pointer  button  (an  event)  saves  that  text  into  memory  (an  action). 

In  this  case,  the  input  event  is  actually  three  separate  X events: 

1 . Pushing  the  first  pointer  button  down. 

2.  Moving  the  pointer  while  holding  the  first  button  down. 

3.  Releasing  the  button. 

Each  of  these  input  events  performs  part  of  the  action  of  selecting  text: 

1.  Unselects  any  previously  selected  text  and  begins  selecting  new  text. 

2.  Extends  the  selection. 

3.  Ends  the  selection,  saving  the  text  into  memory  (both  as  the  PRIMARY  selection  and 

CUT_BUFFERO). 

The  event  and  action  mappings  would  be  expressed  in  a translation  table  as  follows: 

<BtnlDown>:  select-start () \n\ 

<BtnlMotion> : select-extend ( ) \n\ 

<BtnlUp> : select-end (PRIMARY, CUT_BUFFERO) 

where  each  event  is  enclosed  in  angle  brackets  (<>)  and  produces  the  action  that  follows  the 
colon.  A space  or  tab  generally  precedes  the  action,  though  this  is  not  mandatory: 

<event>:  action 

A translation  table  must  be  a continuous  string.  In  order  to  link  multiple  mappings  as  a con- 
tinuous string,  each  event-action  line  should  be  terminated  by  a newline  character  (\n),  which 
is  in  turn  followed  by  a backslash  (\)  to  escape  the  actual  newline. 

These  are  default  translations  for  xterm*  All  of  the  events  are  simple,  comprised  of  a single 
button  motion.  As  we’ll  see,  events  can  also  have  modifiers,  i.e.,  additional  button  motions 
or  keystrokes  (often  Control  or  Meta)  that  must  be  performed  with  the  primary  event  to  pro- 
duce the  action.  (Events  can  also  have  modifiers  that  must  not  accompany  the  primary  event 
if  the  action  is  to  take  place.) 

As  you  can  see,  the  default  actions  listed  in  the  table  are  hardly  intuitive.  The  event-action 
mappings  that  can  be  modified  using  translation  resources  are  usually  described  on  the  refer- 
ence page  for  the  particular  client. 


♦They  are  actually  slightly  simplified  versions  of  default  translations.  Before  you  can  understand  the  actual  transla- 
tions listed  on  the  xterm  reference  page  in  Part  Three  of  this  guide,  you  must  learn  more  about  the  syntax  of  transla- 
tions. In  addition  to  the  current  chapter,  read  Appendix  II,  Translation  Table  Syntax. 


Setting  Resources 


189 


Setting  Resources 


You  can  specify  non-default  translations  using  a translation  table  (a  resource  containing  a list 
of  translations).  Since  actions  are  part  of  the  client  application  and  cannot  be  modified,  what 
you  are  actually  doing  is  specifying  alternative  events  to  perform  an  action.* 

The  basic  syntax  for  specifying  a translation  table  as  a resource  is  as  follows: 

[ object* l subobject . . . ] ] ‘translations : #override\ 

[modifier] <event> : action 

The  first  line  is  basically  like  any  other  resource  specification,  with  a few  exceptions.  First, 
the  final  argument  is  always  translations,  indicating  that  one  (or  more)  of  the  event- 
action  bindings  associated  with  the  [object*  [subobject  . . . ] ] are  being  modified. 

Second,  note  that  #override  is  not  the  value  of  the  resource;  it  is  literal  and  indicates 
that  what  follows  should  override  any  default  translations.  In  effect,  # over ride  is  no 
more  than  a pointer  to  the  true  value  of  the  resource:  a new  event-action  mapping  (on  the 
following  line),  where  the  event  may  take  a modifier.! 

A non-obvious  principle  behind  overriding  translations  is  that  you  only  literally  “override”  a 
default  translation  when  the  event(s)  of  the  new  translation  match  the  event(s)  of  a default 
translation  exactly.  If  the  new  translation  does  not  conflict  with  any  existing  translation,  it  is 
merely  appended  to  the  defaults. 

In  order  to  be  specified  as  a resource,  a translation  table  must  be  a single  string.  The 
# over  ride  is  followed  by  a backslash  (\)  to  indicate  that  the  subsequent  line  should  be  a 
continuation  of  the  first. 

In  the  basic  syntax  example  above,  the  value  is  a single  event-action  mapping.  The 
value  could  also  be  a list  of  several  mappings,  linked  by  the  characters  \n\  to  make  the 
resource  a continuous  string. 

The  following  xterm  translation  table  shows  multiple  event-action  mappings  linked  in  this 
manner: 

*VT100 . Translations : #override\ 

<BtnlDown>:  select-start () \n\ 

<BtnlMot ion> : select-extend ( ) \n\ 

<BtnlUp> : select-end (PRIMARY, CUT_BUFFERO ) 


*As  we’ll  see,  in  certain  cases  you  may  be  able  to  supply  an  alternative  argument  (such  as  a selection  name)  to  an  ac- 
tion. These  changes  are  interpreted  by  the  resource  manager. 

fThe  use  of  modifiers  can  actually  become  quite  complicated,  sometimes  involving  multiple  modifiers.  For  our  pur- 
poses, we’ll  deal  only  with  simple  modifiers.  For  more  information  on  modifiers,  see  Appendix  H,  Translation  Table 
Syntax,  in  this  guide,  and  Volume  Four,  X Toolkit  Programming  Manual. 
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xterm  Translations  to  Use  xcllpboard 


As  stated  in  Chapter  4,  The  xterm  Terminal  Emulator,  you  can  specify  xterm  translations  to 
have  copied  text  made  the  CLIPBOARD  selection.  The  CLIPBOARD  selection  is  the  property 
of  the  xclipboard  client.  II  you  are  running  xclipboard  and  you  copy  text  to  be  made  the 
CLIPBOARD  selection,  this  text  automatically  appears  in  the  xclipboard  window.  The  xclip- 
board window  allows  you  to  store  text  that  can  then  be  copied  to  other  windows. 

Some  sample  translations  that  would  allow  you  to  use  the  xclipboard  in  this  way  follow: 

* VT 1 0 0 . Tran s la t i ons : f override\ 

Buttonl  <Btn3Down> : select-end (CLIPBOARD) \n\ 

'Ctrl  'Meta  <Btn2Up>:  insert-selection (PRIMARY, CLIPBOARD) 

According  to  this  table,  while  selecting  text  with  Buttonl  (the  modifier),  the  event  of 
pressing  the  third  pointer  button  (Btn3Down)  (while  continuing  to  hold  down  the  first  but- 
ton), produces  the  action  of  making  the  text  the  CLIPBOARD  selection.  (Notice  that  we’ve 
taken  the  select-end  action  and  combined  it  with  the  argument  clipboard.  The  default 
translation  uses  the  arguments  primary, cut_buffero.) 

The  second  line  modifies  the  way  selected  text  is  pasted  into  a window  so  that  the  clip- 
board selection  can  be  pasted.  As  described  in  Chapter  4,  The  xterm  Terminal  Emulator , 
pressing  the  second  pointer  button  pasted  the  contents  of  the  PRIMARY  selection,  by  default. 
If  there  is  no  PRIMARY  selection,  the  contents  of  the  cut  buffer  are  pasted.  The  default  trans- 
lation that  sets  this  behavior  is  as  follows: 

'Ctrl  'Meta  <Btn2Up>:  insert-selection (PRIMARY, CUT_BUFFERO ) 

This  translation  specifies  that  releasing  pointer  button  2,  while  pressing  any  modifier  button 
or  key  other  than  Control  or  Meta,  inserts  text  from  the  PRIMARY  selection,  or  if  the  selec- 
tion is  empty,  from  cut  buffer  0.  In  the  second  line  of  our  translation  table,  we’ve  replaced 
cut_buffero  with  the  clipboard  selection.  The  new  behavior  is  that  releasing  the  second 
pointer  button  pastes  the  PRIMARY  selection,  or  if  there  is  none,  the  CLIPBOARD  selection. 

Thus,  according  to  the  translations  in  the  example,  if  you  select  text  as  usual  with  the  first 
pointer  button,  and  then  additionally  push  the  third  button  down  (while  continuing  to  hold 
the  first  button),  the  text  becomes  the  CLIPBOARD  selection  and  appears  automatically  in  the 
xclipboard  window,  as  in  Figure  9-1. 

Since  our  first  translation  specifies  a different  event/action  mapping  than  the  default  transla- 
tion for  selecting  text  (discussed  in  the  previous  section),  the  default  translation  still  applies. 
If  you  select  text  with  the  first  pointer  button  alone,  that  text  is  still  made  the  PRIMARY  selec- 
tion and  fills  CUT_BUFFER0.  To  send  text  to  the  xclipboard , you  would  need  to  use  the  third 
pointer  button  as  well.  Thus,  not  all  selected  text  need  be  made  the  CLIPBOARD  selection 
(and  sent  automatically  to  the  xclipboard). 

There  are  advantages  to  making  only  certain  selections  CLIPBOARD  selections.  You  can 
keep  xclipboard  running  and  make  many  text  selections  by  the  default  method  (first  pointer 
button),  without  filling  up  the  xclipboard  window.  And  chances  are  you  don’t  want  to  save 
every  piece  of  text  you  copy  for  an  extended  period  of  time,  anyway. 
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Figure  9-1.  Selected  text  appears  automatically  in  the  xclipboard  window 

The  CLIPBOARD  selection  and  the  xclipboard  client  also  get  around  the  potential  problems 
of  selection  ownership  discussed  in  Chapter  4.  Once  text  becomes  the  CLIPBOARD  selection, 
it  is  owned  by  the  xclipboard  client.  Thus,  if  the  client  from  which  text  was  copied  (the  orig- 
inal owner)  goes  away,  the  selection  is  still  available,  owned  by  the  xclipboard , and  can  be 
transferred  to  another  window  (and  translated  to  another  format  if  necessary). 

The  operation  of  many  clients  can  be  modified  by  specifying  event  translations  as  resources. 
See  the  relevant  client  reference  pages  in  Part  Three  of  this  guide. 

For  information  about  events,  actions,  and  translation  table  syntax,  see  Appendix  H,  Transla- 
tion Table  Syntax,  in  this  guide,  and  Volume  Four,  X Toolkit  Programming  Manual. 


How  to  Set  Resources 


Learning  to  write  resource  specifications  is  a fairly  manageable  task,  once  you  understand  the 
basic  rules  of  syntax  and  precedence.  In  contrast,  the  multiple  ways  you  can  set 
resources — for  a single  system,  for  multiple  systems,  for  a single  user,  for  all  users — can  be 
confusing.  For  our  purposes,  we  are  primarily  concerned  with  specifying  resources  for  a 
single  user  running  applications  both  on  the  local  system  and  on  remote  systems  in  a net- 
work. 

As  we’ve  said,  resources  are  generally  specified  in  files.  A resource  file  can  have  any  name 
you  like.  Resources  are  generally  “loaded”  into  the  X server  by  the  xrdb  client,  which  is  nor- 
mally run  from  your  startup  file  or  run  automatically  by  xdm  when  you  log  in.  (See  Appendix 
A,  System  Management,  for  information  about  startup  files  and  xdm.)  Prior  to  Release  2 of  X, 
there  was  only  one  resource  file  called  Xdefaults,  placed  in  the  user’s  home  directory.  If  no 
resource  file  is  loaded  into  the  server  by  xrdb,  the  Xdefaults  file  will  still  be  read. 

Remember  that  X allows  clients  to  run  on  different  machines  across  a network,  not  just  on 
the  machine  that  supports  the  X server.  The  problem  with  the  older  Xdefaults  mechanism 
was  that  users  who  were  running  clients  on  multiple  machines  had  to  maintain  multiple 
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J (defaults  files,  one  on  each  machine.  By  contrast,  xrdb  stores  the  application  resources 
directly  in  the  server,  thus  making  them  available  to  all  clients,  regardless  of  the  machine  the 
clients  are  running  on.  As  we’ll  see,  xrdb  also  allows  you  to  change  resources  without  edit- 
ing files. 

Of  course,  you  may  want  certain  resources  to  be  set  on  all  machines  and  others  to  be  set  only 
on  particular  machines.  See  the  section  “Other  Sources  of  Resource  Definition”  later  in  this 
chapter  for  information  on  setting  machine-specific  resources.  This  section  gives  an  over- 
view of  additional  ways  to  specify  resources,  using  a variety  of  system  files. 

In  addition  to  loading  resource  files,  you  can  specify  defaults  for  a particular  instance  of  an 
application  from  the  command  line  using  two  options:  -xrm  and  -name. 

First  we’ll  consider  a sample  resources  file.  Then  we’ll  take  a look  at  the  use  of  the  -xrm 
and  -name  command  line  options.  Finally,  we’ll  discuss  various  ways  you  can  load 
resources  using  the  xrdb  program  and  consider  “Other  Sources  of  Resource  Definition.” 

A Sample  Resources  File 

Figure  9-2  shows  a sample  resources  file.  This  file  sets  the  border  width  for  all  clients  to  a 
default  value  of  2 pixels,  and  sets  other  specific  variables  for  xclock  and  xterm.  The  meaning 
of  each  variable  is  fairly  obvious  from  its  name  (for  example,  xterm*scrollBar : 
True  means  that  xterm  windows  should  be  created  with  a scrollbar. 

Note  that  comments  are  preceded  by  an  exclamation  point  (!). 

For  a detailed  description  of  each  possible  variable,  see  the  appropriate  client  reference 
pages  in  Part  Three  of  this  guide. 

*borderWidth : 2 

i 

! xclock  resources 

i 

xclock*borderWidth : 5 

xclock*geometry : 64x64 


xterm  resources 


xterm*curses : 
xterm*cursorColor : 
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xterm*  jumpScroll : 
xterm*saveLines : 
xterm*scrollBar: 
xterm*scrollKey : 
xterm* background : 
xterm*borderColor : 
xterm*borderWidth : 
xterm*foreground : 
xterm*font : 
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Figure  9-2.  A sample  resources  file 
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Specifying  Resources  from  the  Command  Line 


Two  command  line  options  that  are  supported  by  all  clients  written  with  the  X Toolkit  can  be 
useful  in  specifying  resources. 

The  -xrm  Option 

The  -xrm  option  allows  you  to  set  on  the  command  line  any  specification  that  you  would 
otherwise  put  into  a resources  file.  For  example: 

% xtarm  -xrm  ' xterm*Foraground:  blua'  £ 

Note  that  a resource  specification  on  the  command  line  must  be  quoted  using  the  single 
quotes  in  the  line  above. 

The  -xrm  option  only  specifies  the  resource(s)  for  the  current  instance  of  the  application. 
Resources  specified  in  this  way  do  not  become  part  of  the  resource  database. 

The  -xrm  option  is  most  useful  for  setting  classes,  since  most  clients  have  command  line 
options  that  correspond  to  instance  variable  names.  For  example,  the  -fg  command  line 
option  sets  the  foreground  attribute  of  a window,  but  -xrm  must  be  used  to  set  Fore- 
ground. 

Note  also  that  a resource  specified  with  the  -xrm  option  will  not  take  effect  if  a resource  that 
takes  precedence  has  already  been  loaded  with  xrdb.  For  example,  say  you’ve  loaded  a 
resource  file  that  includes  the  specification: 

xterm*pointerShape : pirate 

The  following  command  line  specification  of  another  cursor  will  fail: 

% xtarm  -xrm  ' * point erSha pa : gumby'  £ 

because  the  resource  xterm*pointerShape  is  more  specific  than  the  resource 
*po  inter  Shape.  Instead,  you’ll  get  an  xterm  with  the  previously  specified  pirate  cursor. 

To  override  the  resource  database  (and  get  the  Gumby  cursor),  you’d  need  to  use  a resource 
as  or  more  specific,  such  as  the  following: 

% xtarm  -xrm  ' xterm*po intar Shapa : gumby'  £ 


The  -name  Option 

The  -name  option,  which  lets  you  name  one  instance  of  a client  using  an  arbitrary  alias,  can 
also  be  used  to  set  resources.  If  a client  supports  the  -name  option,  you  can  create  instance 
resources  using  the  arbitrary  alias  as  the  object.  You  can  then  run  the  client  using  the  alias 
as  the  -name  argument.  The  client  automatically  uses  the  resources  that  begin  with  that 
alias. 

For  example,  you  could  put  the  following  entries  into  a resource  file  such  as  Xresources : 

XTerm*Font:  8x13 

smallxterm*Font : 6x10 
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smallxterm*Geometry : 80x10 
bigxterm*Font : 9x15 

bigxterm*Geometry : 80x55 

You  could  then  use  the  following  commands  to  create  xterms  of  different  sizes: 

% xrtarm  & 

would  create  an  xterm  with  the  default  specifications,  while: 

% xterm  -name  smallxtarm  & 

would  create  a small  xterm,  80  characters  across  by  10  lines  down,  displaying  in  the  font 
6x10.  In  addition: 

% xterm  -name  bigxtarm  & 

would  create  a big  xterm,  80  characters  across  by  55  lines  down,  displaying  in  the  font  9x15. 


Setting  Resources  with  xrdb 


The  xrdb  program  saves  you  from  the  difficulty  of  maintaining  multiple  resource  files  if  you 
run  clients  on  multiple  machines.  It  stores  resources  in  the  X server,  where  they  are  acces- 
sible to  all  clients  using  that  server.  (Technically  speaking,  the  values  of  variables  are  stored 
in  a data  structure  referred  to  as  the  RESOURCE_MANAGER  property  of  the  root  window  of 
screen  0 for  that  server.  From  time  to  time,  we  may  refer  to  this  property  colloquially  simply 
as  the  resource  database.) 

The  appropriate  xrdb  command  line  should  normally  be  placed  in  your  jcinitrc  file  or  jcses- 
sion  file  to  initialize  resources  at  login,  although  it  can  also  be  invoked  interactively.  It  has 
the  following  syntax: 


xrdb  [ options ] [ filename ] 

The  xrdb  client  takes  several  options,  all  of  which  are  documented  on  the  reference  page  in 
Part  Three  of  this  guide.  Several  of  the  most  useful  options  are  discussed  in  subsequent  sec- 
tions. (Those  that  are  not  discussed  here  have  to  do  with  xrdb's  ability  to  interpret  C prepro- 
cessor-style defined  symbols;  this  is  an  advanced  topic.  For  more  information,  see  the  xrdb 
reference  page  in  Part  Three  of  this  guide,  and  the  cpp(  1)  reference  page  in  your  UNIX  Refer- 
ence Manual.) 


The  optional  filename  argument  specifies  the  name  of  a file  from  which  the  values  of  client 
variables  (resources)  will  be  read.  If  no  filename  is  specified,  xrdb  will  expect  to  read  its  data 
from  standard  input.  That  is,  the  program  will  appear  to  hang,  until  you  type  some  data,  fol- 
lowed by  an  end-of-file  (Control-D).  Note  that  whatever  you  type  will  override  the  previous 
contents  of  the  RESOURCE_MANAGER  property,  so  if  you  inadvertently  type  xrdb  without  a 
filename  argument,  and  then  quit  with  Control-D,  you  will  delete  any  previous  values.  (You 
can  append  new  settings  to  current  ones  using  the  -merge  option  discussed  later  in  this 
chapter.) 


The  resource  filename  can  be  anything  you  want.  Two  commonly  used  names  are  Xde- 
faults  and  X resources . 
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You  should  load  a resource  file  with  the  xrdb  -load  option.  For  example,  to  load  the  con- 
tents of  your  Xresources  file  into  the  RESOURCE_MANAGER,  you  would  type: 

% xrdb  -load  .Xresources 


Querying  the  Resource  Database 


You  can  find  out  what  options  are  currently  set  by  using  the  -query  option.  For  example: 


% xrdb  -query 

XTerm* ScrollBar : True 

bigxterm*font : 9x15 

bigxterm*Geometry : 80x55 

smallxterm*Font : 6x10 

smallxterm*Geometry : 80x10 
xterm*borderWidth : 3 


If  xrdb  has  not  been  run,  this  command  will  produce  no  output. 


Loading  New  Values  into  the  Resource  Database 

By  default,  xrdb  reads  its  input  (either  a file  or  standard  input)  and  stores  the  results  into  the 
resource  database,  replacing  the  previous  values.  If  you  simply  want  to  merge  new  values 
with  the  currently  active  ones  (perhaps  by  specifying  a single  value  from  standard  input),  you 
can  use  the  -merge  option.  Only  the  new  values  will  be  changed;  variables  that  were 
already  set  will  be  preserved  rather  than  overwritten  with  empty  values. 

For  example,  let’s  say  you  wanted  to  add  new  resources  listed  in  the  file  new.values.  You 
could  say: 

% xrdb  -merge  new.values 

As  another  example,  if  you  wanted  all  subsequently  run  xterm  windows  to  have  scrollbars, 
you  could  use  standard  input,  and  enter: 

% xrdb  -merge 

xterm* scrollBar:  True 

and  then  press  Control-D  to  end  the  standard  input.  Note  that  because  of  precedence  rules 
for  resource  naming,  you  may  not  automatically  get  what  you  want.  For  example,  if  you 
specify: 

xterm*scrollBar : True 

and  the  more  specific  value: 

xterm*vtl00 . scrollBar : False 

has  already  been  set,  your  new,  less  specific  setting  will  be  ignored.  The  problem  isn’t  that 
you  used  the  -merge  option  incorrectly — you  just  got  caught  by  the  rules  of  precedence. 
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If  your  specifications  don’t  seem  to  work,  use  the  -query  option  to  list  the  values  in  the 
RESOURCE_MANAGER  property,  and  look  for  conflicting  specifications. 

Note  also  that  when  you  add  new  specifications,  they  won’t  affect  any  programs  already  run- 
ning, but  only  programs  started  after  the  new  resource  specifications  are  in  effect.  (This  is 
also  true  even  if  you  overwrite  the  existing  specifications  by  loading  a new  resource  file. 
Only  programs  run  after  this  point  will  reflect  the  new  specifications.) 


Saving  Active  Resource  Definitions  in  a File 

Assume  that  you’ve  loaded  the  RESOURCE_MANAGER  property  from  an  Xresources  or 
other  file.  However,  you’ve  dynamically  loaded  a different  value  using  the  -merge  option, 
and  you’d  like  to  make  the  new  value  your  default. 

You  don’t  need  to  edit  the  file  manually  (although  you  certainly  could.)  The  -edit  option 
allows  you  to  write  out  the  current  value  of  the  RESOURCE_MANAGER  property  into  a file. 
If  the  file  already  exists,  it  is  overwritten  with  the  new  values.  However,  xrdb  is  smart 
enough  to  preserve  any  comments  and  preprocessor  declarations  in  the  file  being  overwritten, 
replacing  only  the  resource  definitions. 

For  example: 

% xrdb  -adit  '/.Xr«»ourc«* 

will  save  the  current  contents  of  the  RESOURCE_MANAGER  property’  in  the  file  Xresources 
in  your  home  directory. 

If  you  want  to  save  a backup  copy  of  an  existing  file,  use  the  -backup  option  as  follows: 

% xrdb  -edit  . mydafaulta  -backup  old 

The  string  following  the  -backup  option  is  used  as  an  extension  to  be  appended  to  the  old 
filename.  In  the  example  shown  above,  the  previous  copy  of  .mydefaults  would  be  saved  as 
.my  defaults. old. 


Removing  Resource  Definitions 

You  can  delete  the  definition  of  the  RESOURCE.MANAGER  property  from  the  server  by  cal- 
ling xrdb  with  the  -remove  option. 

There  is  no  way  to  delete  a single  resource  definition,  other  than  to  read  the  current  xrdb  val- 
ues to  a file.  For  example: 

% xrdb  — quory  > filename 

Use  an  editor  to  edit  and  save  the  file,  deleting  the  resource  definitions  you  no  longer  want: 

% vi  filename 

Then  read  the  edited  values  back  into  the  RESOURCE_MANAGER  with  xrdb : 

% xrdb  —load  filename 
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Listing  the  Current  Resources  for  a Client:  appres 


The  appres  (application  resource)  program,  available  as  of  Release  4,  lists  the  resources  that 
currently  might  apply  to  a client.  These  resources  may  be  derived  from  several  sources, 
including  the  user’s  Xresources  file  and  a system-wide  application  defaults  file.  The  direc- 
tory /usr/lib/Xl  1 /app-defaults  contains  application  default  files  for  several  clients.  The  func- 
tion of  these  files  is  discussed  in  the  next  section.  For  now,  be  aware  that  all  of  the  resources 
contained  in  these  files  begin  with  the  class  name  of  the  application. 

Also  be  aware  that  appres  has  one  serious  limitation:  it  cannot  distinguish  between  valid  and 
invalid  resource  specifications.  It  lists  all  resources  that  might  apply  to  a client,  whether  the 
resources  are  correctly  specified  or  not. 

appres  lists  the  resources  that  apply  to  a client  having  the  class_name  and/or 
instance_name  you  specify.  Typically,  you  would  use  appres  before  running  a client 
program  to  find  out  what  resources  the  client  program  will  access. 

For  example,  say  you  want  to  run  xterm,  but  you  can’t  remember  the  latest  resources  you’ve 
specified  for  it,  whether  you’ve  loaded  them,  or  perhaps  what  some  of  the  application 
defaults  are,  etc.  You  can  use  the  appres  client  to  check  the  current  xterm  resources.  If  you 
specify  only  a class  name,  as  in  the  following  command  line: 

% appres  XTerm 

appres  lists  the  resources  that  any  xterm  would  load.  In  the  case  of  xterm,  this  is  an  extensive 
list,  encompassing  all  of  the  system -wide  application  defaults,  as  well  as  any  other  defaults 
you  have  specified  in  a resource  file. 

You  can  additionally  specify  an  instance  name  to  list  the  resources  applying  to  a particular 
instance  of  the  client,  as  in  the  following: 

% appres  XTerm  bigxterm 

If  you  omit  the  class  name,  xappres  assumes  the  class  -NoSuchClass-,  which  has  no 
defaults,  and  returns  only  the  resources  that  would  be  loaded  by  the  particular  instance  of  the 
client. 


Note  that  the  instance  can  simply  be  the  client  name,  for  example,  xterm.  In  that  case,  none 
of  the  system-wide  application  defaults  would  be  listed,  since  all  begin  with  the  class  name 
XTerm.  For  example,  the  command: 

% appres  xterm 


might  return  resources  settings  similar  to  the  following: 


xterm. vt 100 . scrollBar : 
xterm*PhonyResource : 
xterm*pointerShape : 
xterm* iconGeometry : 
*VT100 . Translations : 

Buttonl  <Btn3Down> 


True 

youbet 

gumby 

+50+50 

#override\ 

select-end (CLIPBOARD) \n\ 


'Ctrl  'Meta  <Btn2Up>:  insert-selection (PRIMARY, CLIPBOARD) 


Most  of  these  resources  set  obvious  features  of  xterm.  The  translation  table  sets  up  xterm  to 
use  the  xclipboard.  Notice  also  that  appres  has  returned  an  invalid  resource  called 
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PhonyResource  that  we  created  for  demonstration  purposes.  You  can’t  rely  on  appres  to 
tell  you  what  resources  a client  will  actually  load,  because  the  appres  program  cannot  distin- 
guish a valid  resource  specification  from  an  invalid  one.  Still  it  can  be  fairly  useful  to  jog 
your  memory  as  to  the  defaults  you’ve  specified  in  your  Xresources  file,  as  well  as  the 
system-wide  application  defaults. 


Other  Sources  of  Resource  Definition 


If  xrdb  has  not  been  run,  the  RESOURCE_MANAGER  property  will  not  be  set  Instead,  the 
resource  manager  looks  for  a file  called  Xdefaults  in  the  user’s  home  directory.  As  we  dis- 
cussed earlier,  resources  found  in  this  way  are  only  available  to  clients  running  on  the  local 
machine. 

Whether  or  not  resources  have  been  loaded  with  xrdb , when  a client  is  run  the  following 
sources  of  resource  definition  are  consulted  in  this  order: 

1.  A file  with  the  same  name  as  the  client  application,  in  the  directory  /usr/lib/Xll/app- 
defaults  will  be  loaded  into  the  resource  manager. 

2.  Files  in  the  directory  named  by  the  environment  variable  XAPPLRESDIR,  or  if  the  vari- 
able is  not  set,  in  the  user’s  home  directory,  with  the  name  Class  where  Class  is  the  class 
name  of  a client  program. 

3.  Resources  loaded  into  the  RESOURCE_MANAGER  property  of  the  root  window  with 
xrdb ; these  resources  are  accessible  regardless  of  the  machine  on  which  the  client  is  run- 
ning. 

If  no  resources  are  loaded  in  this  way,  the  resource  manager  looks  for  a Xdefaults  file  in 
the  user’s  home  directory;  these  resources  are  only  available  on  the  local  machine. 

4.  Next,  the  contents  of  any  file  specified  by  the  shell  environment  variable  XENVIRON- 
MENT  will  be  loaded. 

If  this  variable  is  not  defined,  the  resource  manager  looks  for  a file  named  J (defaults- 
hostname  in  the  user’s  home  directory,  where  hostname  is  the  name  of  the  host  where  the 
client  is  running.  These  methods  are  used  to  set  machine-specific  resources. 

5.  Any  values  specified  on  the  command  line  with  the  -xrn  option  will  be  loaded  for  that 
instance  of  the  program. 

All  of  these  various  sources  of  defaults  will  be  loaded  and  merged,  according  to  the  prece- 
dence rules  described  above  in  the  section  “Precedence  Rules  for  Resource  Specification.” 

The  client  will  then  merge  these  various  defaults  specified  by  the  user  with  its  own  internal 
defaults,  if  any. 

Finally,  if  the  user  has  specified  any  options  on  the  command  line  (other  than  with  the  -xrm 
option),  these  values  will  override  those  specified  by  resource  defaults,  regardless  of  their 
source. 
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Customizing  the 
twm  Window  Manager 

This  chapter  describes  the  syntax  of  the  .twmrc  startup  file  that  can  be  used 
to  customize  the  operation  of  the  twm  window  manager.  It  describes  how  to 
bind  functions  to  keys,  and  how  to  define  your  own  twm  menus.  An  alterna- 
tive .twmrc  file  is  included. 

In  This  Chapter: 

Setting  .twmrc  Variables  205 

Button/Key  Bindings  206 

Pointer  Buttons 206 

Keys  207 

Context 207 

Function  Names  208 

Action  208 

Defining  Menus 209 

Submenus  210 

Executing  System  Commands  from  a Menu  21 1 

Color  Menus 212 

A Complete  Revamp  of  twm  213 
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Customizing  the  twm  Window  Manager 


Difficult  as  it  may  be  to  believe,  every  function  of  the  window  manager  described  in  Chapter 
2 and  Chapter  3 of  this  guide  can  be  modified  by  the  user.  The  function  itself  will  remain  the 
same  (for  example,  you  will  still  resize  a window  by  moving  the  pointer  over  the  border  you 
want  to  change,  and  stretching  or  shrinking  the  window  to  the  size  you  want),  but  the  keys 
and/or  menu  items  used  to  invoke  the  function  may  be  completely  different.  The  flexibility 
of  twm  allows  you  to  redesign  the  Twm  menu  by  reordering,  adding  and  removing  items,  and 
changing  key/button  combinations;  and  to  create  entirely  new  menus.  The  operation  of  the 
window  manager,  as  distributed,  is  controlled  by  a text  file  called  system.twmrc  in  the  direc- 
tory /usr/lib/Xll/twm.  This  file  has  three  parts: 

• A variables  section,  which  contains  various  settings,  such  as  the  font  with  which  menus 
should  be  displayed,  the  volume  of  the  keyboard  bell,  and  so  on. 

• A key  bindings  section,  which  defines  the  keys,  pointer  buttons,  and  key  and  pointer  but- 
ton combinations  that  will  be  used  to  invoke  each  window  manager  function  (including 
the  display  of  menus). 

• A menus  section,  which  defines  the  contents  of  the  menus. 

As  users  gain  experience  with  the  window  manager,  each  can  create  a file  called  .twmrc  in 
his  or  her  home  directory.  This  file  can  simply  extend  system.twmrc , resetting  a variable  or 
two,  perhaps  changing  a key  binding  or  adding  a menu  item — or  it  can  replace  it  completely, 
changing  every  aspect  of  the  way  the  window  manager  operates. 

Rather  than  abstractly  explaining  the  syntax  of  these  various  sections  in  a .twmrc  file,  let’s 
plunge  right  in,  by  looking  at  the  system.twmrc  file  from  the  MIT  XI 1 distribution,  as  shown 
in  Example  10-1.  (Note  that  if  you  are  using  a commercial  version  of  X,  this  file  may  be  sig- 
nificantly different.  However,  in  that  case,  you  most  likely  have  a user’s  guide  specific  to 
your  system — perhaps  even  a customized  version  of  this  one!) 

Example  10-1.  The  system.twmrc  file  from  the  MIT  distribution 

• 

# $XConsort ium : system . twmrc, v 1.7  89/12/01  11:23:47  jim  Exp  $ 

# 

# Default  twm  configuration  file;  needs  to  be  kept  small  to  conserve 

# string  space  in  systems  whose  compilers  don't  handle  medium— sized 

# strings. 
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Example  10-1.  The  system.twmrc  file  from  the  MIT  distribution  (continued) 


# 

# Sites  should  tailor  this  file,  providing  any  extra  title  buttons, 

# menus,  etc.,  that  may  be  appropriate  for  their  environment.  For 

# example,  if  most  of  the  users  were  accustomed  to  uwm,  the  defaults 

# could  be  set  up  not  to  decorate  any  windows  and  to  use  meta-keys. 

# 

NoGrabServer 

DecorateTransients 

Tit leFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 
ResizeFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 
MenuFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 

IconFont  "-adobe-helvet ica-bold-r-normal — *-100-*-*-*-*-*-*" 
IconManagerFont  "-adobe-helvet ica-bold-r-normal — *-100-*-*-* " 
#ClientBorderWidth 

Color 

{ 

BorderColor  "slategrey" 

Def aultBackground  "maroon" 

Def aultForeground  "gray85" 

Tit leBackground  "maroon" 

Tit leForeground  "gray85" 

MenuBackground  "maroon" 

MenuForeground  "gray85" 

MenuTit leBackground  "gray70" 

MenuTit leForeground  "maroon" 

IconBackground  "maroon" 

IconForeground  "gray85" 

IconBorderColor  "gray85" 

IconManagerBackground  "maroon" 

IconManagerForeground  "gray 8 5 " 

} 

# 

# Define  some  useful  functions  for  motion-based  actions. 

# 

MoveDelta  3 

Function  "move-or-lower"  { f.move  f.deltastop  f. lower  } 

Function  "move-or-raise"  { f.move  f.deltastop  f. raise  } 

Function  "move-or-iconif y " { f.move  f.deltastop  f.iconify  } 


# 


# Set  some 

useful 

bindings . 

Sort  of  uwm-ish. 

sort  of  simple-button-i 

Buttonl 

= 

root  : 

f . menu 

"defops" 

Buttonl 

= 

m : 

window | icon 

: f. function 

"move-or-lower" 

Button2 

= 

m : 

window | icon 

: f.iconify 

Button3 

= 

m : 

window | icon 

: f. function 

"move-or-raise" 

Buttonl 

= 

title  : 

f . function 

"move-or-raise" 

Button2 

= 

title  : 

f . raiselower 

Buttonl 

= 

icon  : 

f . function 

"move-or-iconify" 

Button2 

= 

icon  : 

f . iconify 

Buttonl 

= 

iconmgr  : 

f . iconify 

Button2 

iconmgr  : 

f . iconify 
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Example  10-1.  The  system.twmrc  file  from  the  MIT  distribution  (continued) 


# 

# And  a menu  with  the  usual  thinqs 

# 

menu  "defops" 

{ 


'Twm" 

f . title 

'Iconify" 

f . iconify 

'Resize" 

f . resize 

'Move" 

f . move 

'Raise" 

f . raise 

'Lower" 

f . lower 

" 

f . nop 

Focus" 

f . focus 

Unf ocus" 

f . unfocus 

Show  Iconmgr" 

f . showiconmgr 

Hide  Iconmgr" 

f . hideiconmgr 

f . nop 

Kill" 

f . destroy 

Delete" 

f . delete 

n 

f . nop 

Restart" 

f . restart 

Exit" 

f . quit 

} 

If  you  wish  to  change  the  operation  of  the  window  manager,  you  shouldn’t  change  the  sys- 
tem.twmrc file.  Instead,  copy  it  to  your  home  directory,  under  the  name  .twmrc,  and  make 
changes  to  that  copy.  Note  that  settings  in  system.twmrc  and  your  own  local  .twmrc  file  are 
not  cumulative;  even  if  you  only  want  to  make  a small  change,  you  will  need  to  copy  the 
whole  file. 


Setting  .twmrc  Variables 

The  first  section  of  the  file  sets  global  variables.  Some  variables  are  Boolean — that  is,  their 
presence  or  absence  “toggles”  some  attribute  of  the  window  manager — while  others  have  the 
form: 


variable  value 

where  value  is  a number,  a text  string,  keyword,  or  list  of  any  of  these.  Variable  names  and 
keywords  are  case  insensitive. 

An  example  of  a Boolean  variable  is  DecorateTransients,  which,  if  present,  causes 
all  windows  to  have  titlebars,  even  if  they  are  only  intended  to  appear  for  a short  time. 

An  example  of  a text  string  variable  is: 

MenuFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 

which  names  the  font  that  should  be  used  in  all  menus.  Text  string  variables  are  case  sensi- 
tive, and  must  always  be  surrounded  by  double  quotes.  (See  Appendix  E,  Release  3 and  4 
Standard  Fonts , for  lists  and  illustrations  of  fonts  in  the  standard  XI 1 distribution.) 
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An  example  of  a numeric  variable  is: 

IconBorderWidth  5 

which  sets  the  width  of  an  icon’s  window  border  in  pixels. 

In  the  following  example,  TitleHighlight  is  a keyword: 

Pixmaps 

{ 

TitleHighlight  "grayl" 

} 

An  example  of  a list  variable  is: 

NoTitle  { "oclock"  "xclock"  "xscreensaver"  "zwgc"  } 

The  available  variables  are  described  in  detail  on  the  twm  reference  page  in  Part  Three  of  this 
guide,  so  we  won’t  go  into  detail  on  each  of  them  here. 


Button/Key  Bindings 

The  second  section  of  the  .twmrc  file  specifies  which  combination  of  keys,  pointer  buttons, 
and  title  buttons  (and  in  which  context)  will  be  used  to  invoke  each  predefined  twm  function. 
Let’s  see  how  this  works,  by  looking  at  the  first  few  lines  of  the  function  binding  section  of 
system. twmrc. 


# BUTTON/KEY  = 

KEYS 

: CONTEXT  : 

FUNCTION 

ACTION 

Buttonl  = 

: root  : 

f .menu 

"defops" 

Buttonl  = 

m 

: window  I icon 

: f. function 

"move-or-lower 

Button2  = 

m 

: window | icon 

: f.iconify 

The  first  line  we’ve  shown  is  just  a comment  line,  which  is  not  present  in  the  original  file.  It 
labels  each  of  the  fields  in  the  line  below.  The  first  field  is  separated  from  the  others  by  an 
equals  sign;  subsequent  fields  are  separated  by  colons.  In  system. twmrc,  fields  are  separated 
by  tabs  for  clarity,  making  the  colons  (falsely)  appear  to  be  delimiters  only  for  the  context 
field;  they  could  instead  follow  each  other  without  intervening  whitespace. 

Let’s  talk  about  each  of  the  fields  in  turn. 


Pointer  Buttons 

The  first  field  defines  which  keys  or  pointer  buttons  are  used  to  invoke  the  function. 

twm  can  handle  a pointer  with  up  to  five  buttons,  which  would  be  named  Buttonl,  Button2, 
Button3,  Button4,  and  Button5.  To  bind  a key  to  a twm  function,  just  use  that  key’s 
keysym — the  name  that  represents  the  label  on  a key.  For  example,  the  keysym  for  the  FI 
key  on  a DECstation  3100  is  “FI”.  For  more  information  about  keysyms,  see  Chapter  11, 
Setup  Clients. 
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The  second  field  lists  modifier  keys,  if  any,  which  must  be  held  down  while  invoking  the 
specified  function,  twm  recognizes  the  Shift,  Control  and  Meta  keys.  (See  Chapter  1 1 Setup 
Clients,  for  more  discussion.)  These  names  must  be  entered  in  the  .twmrc  file  in  lower  case 
and  can  be  abbreviated  s,  c,  and  m. 

If  two  keys  must  be  held  down  at  once,  the  names  should  be  separated  by  a vertical  bar  ( | ) 
For  example,  c | s would  mean  that  the  Control  and  Shift  keys  should  be  pressed  simulta- 
neously. It  is  not  permissible  to  bind  a function  to  three  keys  at  once.  If  the  field  is  left 
blank,  no  key  needs  to  be  pressed  while  invoking  the  function. 

Control  and  Shift  should  be  familiar  to  most  users.  But  what  is  a “Meta”  key?  There  isn’t  a 
key  by  that  name  on  many  keyboards— instead,  Meta  is  a user-definable  Control  key  that  can 
be  mapped  to  an  actual  key  on  the  physical  keyboard  using  the  xmodmap  client  as  described 
in  Chapter  11.  Most  implementations  of  X will  include  a mapped  Meta  key.  Type  xmodmap 
without  any  arguments  to  display  the  map.  The  system.twmrc  specifies  the  Meta  key  in  many 
keyboard  bindings.  On  workstations  without  a special  key  corresponding  to  Meta,  you  will 
have  to  use  xmodmap  to  find  out  or  change  the  definition  of  Meta  to  something  reasonable. 

Meta  could  be  mapped  to  the  Control  key,  although  this  could  potentially  lead  to  conflicts 
with  applications  that  want  to  use  the  Control  key.  In  particular,  certain  functions  of  xedit 
will  operate  strangely  or  not  at  all  if  Meta  is  mapped  to  Control. 

If  you  want  to  map  the  Meta  key,  it  is  best  to  choose  a keyboard  key  that’s  within  easy  reach 
and  is  not  used  frequently  for  other  applications  (perhaps  an  Alt  or  Funct  key).  Left-  or  right- 
handedness  could  also  be  a factor  in  choosing  a Meta  key. 

Some  X developers  warn  against  binding  functions  to  the  Shift  key  alone,  since  they  say  cer- 
tain applications  use  it  as  a Control  key.  If  you  use  it  in  twm,  it  will  perform  both  functions 
simultaneously,  which  is  likely  to  be  confusing.  For  the  same  reason,  you  should  not  bind 
functions  to  buttons  without  modifier  keys  in  the  context  of  a window,  as  an  application  may 
want  to  use  the  pointer  buttons  for  its  own  purposes. 


Context 

The  third  field  defines  the  context — the  location  the  pointer  must  be  in  before  the  function 
can  be  invoked.  This  field  may  be  blank,  or  may  contain  one  or  more  of:  window,  title,  icon, 
root,  frame,  iconmgr,  their  first  letters  (icon  is  i,  iconmgr  is  m),  or  all.  Multiple  context  speci- 
fications should  be  separated  by  vertical  bars. 

If  root  is  specified,  it  means  that  the  pointer  must  be  in  the  root  (background)  window,  and 
not  in  any  other  window  or  icon.  If  the  context  is  window,  icon,  title,  frame,  or  iconmgr,  the 
pointer  must  be  in  the  specified  place(s)  for  the  function  to  be  invoked. 

The  context  field  makes  perfect  sense  if  you  consider  the  sample  function  binding: 

Button2  = m : window | icon  : f.iconify 

f . iconif  y turns  a window  into  an  icon,  or  an  icon  into  a window.  The  pointer  must  be  in 
a window  or  an  icon  for  the  function  to  be  used. 
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Function  Names 


The  first  field  in  a key  binding  contains  the  name  of  a function,  followed  by  an  equals  sign. 

twm  has  a number  of  predefined  functions.  Each  of  these  functions  has  a name  beginning 
with  “f  . The  meaning  of  most  of  these  functions  should  be  fairly  obvious  to  you  from  the 
name,  if  not  from  your  experience  using  the  window  manager.  For  example,  f . resize  is 
used  to  resize  a window,  f .move  to  move  a window,  or  f . iconify  to  change  a window 
to  an  icon. 

Others  are  less  obvious.  For  example,  f . identify  provides  a summary  of  the  name  and 
geometry  of  the  window  it’s  invoked  on.  Notice  the  function  f . nop,  which  appears  coupled 
with  a set  of  empty  quotes  rather  than  a menu  selection.  This  line  in  the  .twmrc  creates  a 
blank  line  on  the  Twm  menu,  to  isolate  the  KillWindow  and  Exit  selections  from  the  others.  If 
you  select  the  blank  line,  nothing  happens.  If  you  substituted  f . beep  for  f . nop,  the  key- 
board would  beep  when  the  blank  line  was  selected. 

Each  of  the  functions  is  described  in  detail  on  the  reference  page  for  twm  in  Part  Three  of  this 
guide. 


Action 

The  fifth  field,  labeled  “Action,”  is  typically  used  only  for  the  f .menu  and  f . function 
functions,  which  allow  you  to  invoke  user-defined  menus  and  functions.  The  fifth  field  speci- 
fies the  name  of  a menu  or  function,  whose  contents  are  defined  in  the  third  section  of  the 
.twmrc  file.  If  the  menu  or  function  name  contains  quotes,  special  characters,  parentheses, 
tabs  or  blanks,  it  must  be  enclosed  in  double  quotes.  For  consistency,  you  may  want  to 
always  quote  menu  and  function  names.  For  example: 

Buttonl  = : root  : f .menu  "defops" 

Buttonl  =m|s  : w|t|i|f|m  : f .menu  "defops" 

Button3  = : root  : f .menu  "utilities" 

Going  back  to  our  sample  function  binding: 

Buttonl  = : root  : f.menu  "defops" 

you  can  now  understand  that  the  f .menu  function  is  invoked  (bringing  up  the  menu  named 
“defops”)  by  moving  the  pointer  to  the  root  window  and  pressing  the  left  pointer  button. 

All  of  the  other  function  definitions  should  be  equally  readable  to  you.  Go  back  for  a 
moment  and  review  the  bindings  shown  in  the  system.twmrc  file  in  Example  10-1. 

You’ll  notice  that  it  is  possible  to  bind  the  same  function  to  more  than  one  set  of  keys,  but- 
tons, and/or  contexts.  For  example,  the  f . iconify  function  can  be  invoked  while  on  a 
window  by  pressing  the  Meta  key  together  with  the  middle  button  on  the  pointer.  But  when 
the  pointer  is  in  the  icon,  you  can  invoke  this  function  by  pressing  only  the  middle  button  on 
the  pointer.  The  reason  for  this  becomes  obvious  if  you  realize  that  when  the  pointer  is  on  a 
window,  the  middle  pointer  button  alone  might  have  some  other  meaning  to  the  application 
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running  m that  window.  In  order  to  avoid  conflict  with  other  applications,  twm  uses  the  more 
complex  key/button  combination.  But  when  the  pointer  is  in  an  icon  or  in  the  root  window 
there  is  no  possibility  of  conflict,  and  it  can  take  a more  forgiving  approach. 


Defining  Menus 


The  third  section  of  a .twmrc  file  contains  menu  definitions.  These  definitions  have  the 
format: 

menu  " menu_name"  { 

"it  em_name"  action 


) 


The  menu  name  must  exactly  match  a name  specified  with  the  f .menu  function. 

Each  item  on  the  menu  is  given  a label  ( item_name ),  which  will  appear  on  the  menu.  This 
is  followed  by  the  action  to  be  performed.  The  action  may  be  one  of  twm's  functions,  or  if 
prefixed  by  a ! character,  it  can  be  a system  command  to  be  executed,  as  if  in  an  xterm  win- 
dow. The  Utilities  menu  shown  in  Example  10-2  demonstrates  both  types  of  action. 


Example  1 0-2.  The  Utilities  menu 


menu  = "Utilities 
"Identify" 

"Source  .twmrc" 

"Check  Mail" 
"Clock" 

"New  Window" 
"Phase  of  Moon" 

tf  r« 

"news" 


"mintaka 


} 


{ 

f . identify 
f . twmrc 
f . beep 

! "/usr/bin/Xll/xbiff  -display  $DISPLAY&" 

! "/usr/bin/Xll/oclock  -display  $DISPLAY  &" 

! "/usr/bin/Xll/xterm  -is  -display  $DISPLAY  &" 

! "/usr/bin/Xl 1/xphoon  &" 
f . beep 

! "/usr/bin/Xl 1/xhost  news.mit.edu; 

/usr/bin/Xll/xterm  -title  news.mit.edu 
-e  rlogin  news.mit.edu  &" 

!" /usr/bin/Xl 1/ xhost  mintaka.lcs.mit.edu; 

/usr/bin/Xll/xterm  -title  mintaka.lcs.mit.edu 
-e  rlogin  mintaka.lcs.mit.edu  &" 


New  Window  is  accomplished  by  running  another  instance  of  xterm.  CheckMail,  Clock, 
PhaseofMoon,  news,  and  mintaka  are  also  implemented  by  running  a system  function.  The 
other  functions  are  accomplished  simply  by  invoking  one  of  twm's  predefined  functions. 

The  Preferences  menu  shown  in  Example  10-3  simply  invokes  xset  with  a number  of  differ- 
ent options: 
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Example  1 0-3.  The  Preferences  menu 


menu  "Preferences"  { 


Bell  Loud" 

! "xset 

b 

80&" 

Bell  Normal" 

! "xset 

b 

onS  " 

Bell  Off" 

! "xset 

b 

offs" 

Click  Loud" 

! "xset 

c 

80&" 

Click  Soft" 

! "xset 

c 

on&  " 

Click  Off" 

! "xset 

c 

offs" 

Lock  On" 

! "xset 

led  on&" 

Lock  Off" 

! "xset 

led  offs 

Mouse  Fast" 

! "xset 

m 

4 2& " 

Mouse  Normal" 

! "xset 

m 

2 5 & " 

Mouse  Slow" 

! "xset 

m 

1 1&" 

} 


Submenus 


While  the  menu  defined  by  the  system.twmrc  file  is  a drastic  improvement  over  the  cluttered 
menus  provided  by  uwm  in  previous  releases  of  XI 1,  it  is  still  far  from  complete.  We’d  like 
to  modify  it  to  add  a couple  of  menus  which  contain  commands  that,  while  still  worth  putting 
in  a menu,  aren’t  used  as  frequently  as  the  commands  in  the  Twm  menu. 

For  the  moment,  let’s  assume  that  we  want  to  leave  the  variable  definitions  and  function  key 
bindings  alone,  but  want  to  add  two  submenus  to  the  Twm  menu.  For  example,  we  might 
copy  system.twmrc  to  a local  .twmrc  file,  and  modify  the  menus  section  to  be  like  the  one 
shown  in  Example  10-4. 


Example  10-4.  Window  operations  divided  into  three  menus 


menu  "defops" 
{ 


'Twm" 

f . t it le 

'Iconify" 

f . iconify 

Resize" 

f . resize 

Move" 

f . move 

Raise" 

f . raise 

Lower" 

f . lower 

•I 

f . nop 

1 . . Utilities" 

f.menu  "Utilit 

1 . . Preferences" 

f.menu  "Prefer 

■I 

f . nop 

'Focus" 

f . focus 

'Unfocus" 

f . unfocus 

'Show  Iconmgr" 

f . showiconmgr 

'Hide  Iconmgr" 

f . hide iconmgr 

i •• 

f . nop 

'Kill" 

f . destroy 

'Delete" 

f . delete 

in 

f . nop 

'Restart " 

f . restart 

'Exit" 

f . quit 

} 


menu  "Utilities"  { 
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nni 


Example  10-4.  Window  operations  divided  into  three  menus  (continued) 


"Utilities" 

"Identify" 
"Source  .twmrc" 

ff  ft 

"Mail  Box" 
"Clock" 

"New  Window" 
"Phase  of  Moon" 

"news" 


"mintaka" 


} 


f .title 
f . beep 
f . identify 
f . twmrc 
f . beep 

! "/usr/bin/Xll/xbiff  -display  $DISPLAY&" 

! "/usr/bin/Xll/oclock  -display  $DISPLAY  &" 

! "/usr/bin/Xll/xterm  -Is  -display  $DISPLAY  &" 

! "/usr/bin/Xl 1/xphoon  &" 
f . beep 

! "/usr/bin/Xl 1/xhost  news.mit.edu; 

/usr/bin/Xll/xterm  —title  news.mit.edu 
-e  rlogin  news.mit.edu  &" 

! "/usr/bin/Xl 1/xhost  mintaka.lcs.mit.edu; 

/usr/bin/Xll/xterm  —title  mintaka.lcs.mit.edu 
-e  rlogin  mintaka.lcs.mit.edu  &" 


menu  "Preference 
"Preferences"  f 
"Bell  Loud" 

"Bell  Normal" 
"Bell  Off" 

"Click  Loud" 
"Click  Soft" 

J "Click  Off" 

"Lock  On" 

"Lock  Off" 

"Mouse  Fast" 
"Mouse  Normal" 
"Mouse  Slow" 

■ > 


s"  { 

.title 

"xset  b 80s " 
"xset  b ons" 
"xset  b offs" 
"xset  c 80&" 
"xset  c on&" 
"xset  c offs" 
"xset  led  on&" 
"xset  led  offs' 
"xset  m 4 2&” 
"xset  m 2 5&" 
"xset  m 1 1&” 


To  get  from  one  menu  to  another,  we  simply  define  f . menu  as  the  action  for  one  item  on  the 
menu.  No  key,  button,  or  context  is  defined,  so  we  go  right  to  the  next  menu  when  selecting 
that  item. 


Executing  System  Commands  from  a Menu 

We  mentioned  above  that  it  is  possible  to  specify  a system  command  as  a menu  action  simply 
by  placing  an  exclamation  point  in  front  of  the  string  to  be  executed. 

It  is  easy  to  cook  up  a menu  that  contains  a miscellany  of  useful  commands,  as  shown  in 
Example  10-5. 

Example  10-5.  A Useful  Commands  menu 

Buttonl  = : root  : f.menu  "Useful  Commands" 

. 

menu  "Useful  Commands"  { 

Analog  clock  ! "xclock  —geometry  162x162— 10+10& " 
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Example  10-5.  A Useful  Commands  menu  (continued) 


Digital  clock 
Edit  File 
Calculator 
Mailbox 

Display  keyboard  mappings 
} 


! "xclock  -digital  -geometry  162x37-10+174&" 
! "xterm  -e  vi" 

!"xcalc  -geometry  126x230-180+10&" 

!"xbiff  -geometry  65x65-353+10&" 

! "xmodmaps " 


As  you  can  quickly  see,  you  can  run  any  window-based  programs  directly,  but  you  need  to 
run  other  programs  using  xterm' s -e  option  (discussed  in  Chapter  4,  The  xterm  Terminal 
Emulator).  You  are  limited  only  by  your  imagination  in  what  commands  you  might  want  to 
put  on  a menu.  Each  command  runs  in  its  own  window,  but  that  isn’t  necessarily  the  case,  as 
we’ll  see  in  a moment. 


Color  Menus 


So  far,  we’ve  assumed  that  all  menus  are  black  and  white.  But  you  can  also  create  color 
menus.  You  can  even  assign  different  colors  to  the  menu  title,  the  highlighting  bar  (the  hori- 
zontal band  that  follows  the  pointer  within  the  menu  and  shows  which  item  is  selected)  and 
the  individual  selections  on  the  menu. 

Colors  are  added  to  menus  when  they’re  defined,  using  optional  arguments.  In  Example 
10-6,  we  show  a “colorized”  version  of  the  Preferences  menu  that  we  defined  earlier. 


Example  1 0-6.  A menu  with  color  definitions 
menu  "Preferences"  ( "WhiteSmoke" 


"Preferences" 
"Bell  Loud" 
"Bell  Normal" 
"Bell  Off" 
"Click  Loud" 
"Click  Soft" 
"Click  Off" 
"Lock  On" 
"Lock  Off" 
"Mouse  Fast" 
"Mouse  Normal 
"Mouse  Slow" 

} 


("DarkSlateGray" 
("DarkSlateGray" 
( "DarkSlateGray" 
( "DarkSlateGray" 
( "DarkSlateGray" 
( "DarkSlateGray" 
( "DarkSlateGray" 


("DarkSlateGray" 
( "DarkSlateGray" 
( "DarkSlateGray" 


"HotPink"  ) { 

"thistle")  f. title 


"bisquel") 
"bisquel " ) 
"bisquel") 
"azurel") 
"azurel " ) 
"azurel") 


"goldl " ) 
"goldl " ) 
"goldl " ) 


"xset  b 80&" 
"xset  b on&" 
"xset  b offs" 
"xset  c 80&" 
"xset  c on&" 
"xset  c off&" 
"xset  led  onS" 
"xset  led  off&" 
"xset  m 4 2&" 
"xset  m 2 5&" 
"xset  m 1 1&" 


In  this  example,  WhiteSmoke  and  HotPink  are  the  foreground  and  background  (respectively) 
of  a highlighted  menu  item.  The  colors  defined  for  each  menu  item  are  the  foreground  and 
background  colors  (in  that  order)  for  that  item  when  it  is  not  highlighted.  The  default  fore- 
ground and  background  colors  for  menu  items  are  controlled  by  the  variables  Menu- 
Foreground  and  MenuBackground. 

twm  has  eighteen  variables  controlling  different  aspects  of  its  color: 

BorderColor  The  default  color  of  a window’s  border. 
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BorderTileBackground 

BorderTileForeground 

Default Background 

Default Foreground 

IconBackground 
I conFo reground 
IconBorderColor 
I conManager Background 
I conManager Foreground 
IconManagerHighlight 

MenuBackground 
MenuFo reground 
Menu ShadowCo lor 
MenuTitleBackground 
MenuTitleFo reground 
Tit leBackground 
T it leFo reground 


The  default  background  color  of  the  gray  pattern  used  in  an 
unhighlighted  window  border. 

The  default  foreground  color  of  the  gray  pattern  used  in  an 
unhighlighted  window  border. 

The  background  color  to  be  used  for  sizing  and  information 
windows. 

The  foreground  color  to  be  used  for  sizing  and  information 
windows. 

The  background  color  of  icons. 

The  foreground  color  of  icons. 

The  default  color  of  an  icon’s  border. 

The  background  color  to  use  for  icon  manager  entries. 

The  foreground  color  to  use  for  icon  manager  entries. 

The  border  color  used  when  highlighting  the  icon  manager 
entry  which  has  the  focus. 

The  background  color  used  for  menus. 

The  foreground  color  used  for  menus. 

The  color  used  for  the  shadow  behind  pull-down  menus. 

The  background  color  of  the  highlighting  bar. 

The  background  color  of  the  highlighting  bar. 

The  background  color  of  the  highlighting  bar. 

The  background  color  of  the  highlighting  bar. 


These  variables  are  most  commonly  used  as  arguments  to  the  Color  and  Monochrome 
variables,  as  seen  in  Example  10-1. 

Colors  can  be  specified  either  with  color  names  or  hex  strings,  as  described  in  Chapter  8, 
Command  Line  Options. 


A Complete  Revamp  of  twm 

Using  the  various  techniques  described  in  this  chapter,  we’ve  modified  the  system.twmrc  file 
to  create  an  interface  we  think  is  more  helpful  to  the  average  user. 

Our  modified  .twmrc  file  sets  up  three  pull-right  menus,  each  with  a slightly  different  focus. 
The  second  menu  offers  some  utilities,  including  oclock  and  xcalc,  and  some  system  com- 
mands, such  as  rlogin.  The  final  menu  is  a Preferences  menu,  which  sets  different  keyclick 
volumes,  leds,  and  pointer  speeds  than  the  default. 

You  can  test  our  .twmrc,  shown  in  Example  10-7,  or  just  use  it  as  a touchstone  to  create  your 
own. 
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Example  10-7.  Modified  .twmrc  file 

# 

# O'Reilly  custom  .twmrc,  modified  from  the  X11R4  system. twmrc 

NoGrabServer 
AutoRelativeResize 
Decorat eTransients 
UsePPosition  "on" 

RestartPreviousState 
Sort IconManager 
ShowIconManager 
IconifyByUnmapping 
NoTitle 
{ 

"oclock" 

"xclock" 

"xscreen saver" 

"zwgc" 

} 

Tit leFont  "-adobe-helvet ica-bold-r-normal — *—120—*—*— *-*—*-*" 
ResizeFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 
MenuFont  "-adobe-helvet ica-bold-r-normal — *-120-*-*-*-*-*-*" 
IconFont  "-adobe-helvet ica-bold-r-normal — *-100-*-*-*-*-*-*" 
IconManagerFont  "-adobe-helvet ica-bold-r-normal — *-100-*-*-*" 

Color 

{ 

BorderColor  "slategrey" 

DefaultBackground  "maroon" 

DefaultForeground  "gray85" 

Tit leBackground  "maroon" 

Tit leForeground  "gray85" 

MenuBackground  "maroon" 

MenuForeground  "gray85" 

MenuTit leBackground  "gray70" 

MenuTitleForeground  "maroon" 

IconBackground  "maroon" 

IconForeground  "gray85" 

IconBorderColor  "gray85" 

IconManagerBackground  "maroon" 

IconManagerForeground  "gray85" 

} 

# 

# Define  some  useful  functions  for  motion-based  actions. 

# 

MoveDelta  3 

Function  "move-or-lower"  { f.move  f.deltastop  f. lower  } 
Function  "move-or-raise"  { f.move  f.deltastop  f. raise  } 
Function  "move-or-iconif y"  { f.move  f.deltastop  f.iconify  } 


# 


# Set  some 

useful  bindings. 

Sort  of  uwm-ish. 

sort  of  simple-button 

Buttonl  = 

: root  : 

f .menu 

"defops” 

Button2  = 

: root  : 

f .menu 

"Preferences" 

Button3  = 

: root  : 

f .menu 

"Utilities" 

Buttonl  = 

m : window | icon 

: f. function 

"move-or-lower" 
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Example 

10-7.  Modified  .twmrc  file  (continued) 

Button2 

Button3 

- m : window | icon  : 
= m : window | icon  : 

: f.iconify 
f. function 

"move-or-raise" 

Buttonl 

Button2 

= : title  : 

- : title  : 

f . function 
f . raiselower 

"move-or-raise" 

Buttonl 

Button2 

= : icon  : 

: icon  : 

f . function 
f . iconify 

"move-or-iconify 

Buttonl 

Button2 

JL 

: iconmgr  : 

= : iconmgr  : 

f . iconify 
f . iconify 

fr 

# And  a 

menu  with  the  usual  things 

menu  "defops" 

{ 

"Twm" 

f .title 

"Iconify" 

f . iconify 

"Resize" 

f . resize 

"Move" 

f . move 

"Raise" 

f . raise 

"Lower" 

f . lower 

f . nop 

" . .Utilities" 

f.menu  "Uti 

".  .Preferences" 

f.menu  "Pre 

n »• 

f . nop 

"Focus" 

f . focus 

"Unfocus" 

f . unfocus 

"Show  Iconmgr" 

f . showiconmgr 

"Hide  Iconmgr" 

f . hideiconmgr 

f . nop 

"Kill" 

f . destroy 

"Delete" 

f . delete 

It  IT 

f . nop 

"Restart" 

f . restart 

"Exit" 

f . quit 

} 


menu  "Utilities"  { 


"Utilities" 

f . title 

" '* 

f . beep 

"identify" 

f . identify 

"source  .twmrc" 

f . twmrc 

" " 

f . beep 

"mail  box" 

! "/usr/bin/Xl 1/xbif f -display  $DISPLAY&" 

"clock" 

! "/usr/bin/Xll/oclock  -display  SDISPLAY  &" 

"xterm" 

! "/usr/bin/Xl 1/xterm  -Is  -display  $DISPLAY  &" 

"xphoon" 

! "/usr/bin/Xll/xphoon  &" 

■V  11 

f . beep 

"news" 

! "/usr/bin/Xl 1/xhost  news.mit.edu; 

/usr/bin/Xl 1/xterm  -title  news.mit.edu 
-e  rlogin  news.mit.edu  &" 

"mintaka" 

! "/usr/bin/Xl 1/xhost  mintaka .lcs.mit.edu; 

/usr/bin/Xll/xterm  -title  mintaka . lcs . i 
-e  rlogin  mintaka.lcs.mit.edu  &" 
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Example  10-7.  Modified  .twmrc  file  (continued) 


menu  "Preferences"  { 

"Preferences"  ( "DarkSlateGray"  : "thistle")  f. title 


"Bell  Loud" 

( "HotPink" 

"bisquel " ) 

! "xset 

b 

80&" 

"Bell  Normal" 

( "HotPink" 

"bisquel " ) 

! "xset 

b 

onS  " 

"Bell  Off" 

( "HotPink" 

"bisquel " ) 

! "xset 

b 

of  f & 

"Click  Loud" 

( "HotPink" 

"azurel " ) 

! "xset 

c 

80  & " 

"Click  Soft" 

( "HotPink" 

"azurel " ) 

! "xset 

c 

onS" 

"Click  Off" 

( "HotPink" 

"azurel" ) 

! "xset 

c 

offs 

"Lock  On" 

! "xset  led  on&" 

"Lock  Off" 

! "xset  led  off&" 

"Mouse  Fast" 

( "HotPink" 

"goldl " ) 

! "xset 

m 

4 2& 

"Mouse  Normal" 

( "HotPink" 

"goldl") 

! "xset 

m 

2 5& 

"Mouse  Slow" 

( "HotPink" 

"goldl " ) 

! "xset 

m 

1 1& 

} 
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Setup  Clients 

Ttlis  chapter  describes  three  useful  setup  clients  that  can  be  used  to  custom- 
ize the  appearance  of  your  display,  and  the  operation  of  your  keyboard  and 
pointer. 

In  This  Chapter: 

xset:  Setting  Display  and  Keyboard  Preferences 219 

Keyboard  Bell  219 

Bug  Compatibility  Mode  220 

Keyclick  Volume  220 

Enabling  or  Disabling  Auto-repeat 221 

Changing  or  Rehashing  the  Font  Path  221 

Keyboard  LEDs  221 

Pointer  Acceleration 222 

Screen  Saver 222 

Color  Definition 223 

Help  with  xset  Options  223 

xsetroot:  Setting  Root  Window  Characteristics 224 

Setting  Root  Window  Patterns  224 

Foreground,  Background  Color  and  Reverse  Video 225 

Changing  the  Root  Window  Pointer 226 

xmodmap:  Modifier  Key  and  Pointer  Customization  227 

Keycodes  and  Keysyms 229 

Procedure  to  Map  Modifier  Keys 230 

Displaying  the  Current  Modifier  Key  Map  230 

Determining  the  Default  Key  Mappings  231 

Matching  Keysyms  with  Physical  Keys  Using  xev  232 

Changing  the  Map  with  xmodmap 233 

Expressions  to  Change  the  Key  Map  234 

Key  Mapping  Examples  235 

Displaying  and  Changing  the  Pointer  Map 236 
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Setup  Clients 


This  chapter  discusses  how  to  set  up  certain  features  of  your  working  environment,  using  the 
following  clients: 

xset  To  set  certain  characteristics  of  the  keyboard,  pointer  and  display. 

xsetroot  To  set  root  window  characteristics. 

xmodmap  To  change  pointer  and  modifier  key  mappings. 

xset:  Setting  Display  and  Keyboard  Preferences 


The  xset  client  allows  you  to  set  an  assortment  of  user  preference  options  for  the  display  and 
keyboard.  Some  of  these  are  followed  by  on  or  off  to  set  or  unset  the  option.  Note  that  xset 
is  inconsistent  in  its  use  of  a dash  (-)  as  an  option  flag.  Some  options  use  a preceding  to 
indicate  that  a feature  be  disabled;  this  can  be  confusing  at  first  to  users  accustomed  to  seeing 
as  an  introductory  symbol  on  all  options. 

Although  xset  can  be  run  any  time,  it  is  suggested  that  you  run  it  at  startup.  These  settings 
reset  to  the  default  values  when  you  log  out.  Not  all  X implementations  are  guaranteed  to 
honor  all  of  these  options. 

Keyboard  Bell 

The  b option  controls  bell  volume  (as  a percentage  of  its  maximum),  pitch  (in  hertz),  and 
duration  (in  milliseconds).  It  accepts  up  to  three  numerical  parameters: 

b volume  pitch  duration 

If  no  parameters  are  given,  the  system  defaults  are  used.  If  only  one  parameter  is  given,  the 
bell  volume  is  set  to  that  value.  If  two  values  are  listed,  the  second  parameter  specifies  the 
bell  pitch.  If  three  values  are  listed,  the  third  one  specifies  the  duration. 

For  example,  the  command: 

% xset  b 70  1000  100 

sets  the  volume  of  the  keyboard  bell  to  70  percent  of  the  maximum,  the  pitch  to  1000  hertz, 
and  the  duration  to  100  milliseconds. 


Setup  Clients 


219 


Setup  Clients 


Note  that  bell  characteristics  vary  with  different  hardware.  The  X server  sets  the  characteris- 
tics of  the  bell  as  closely  as  it  can  to  the  user’s  specifications. 

The  b option  also  accepts  the  parameters  on  or  of  f.  If  you  specify  xset  b on,  system 
defaults  for  volume,  pitch  and  duration  are  used. 

The  bell  can  also  be  turned  off  with  the  option  -b,  or  by  setting  the  volume  parameter  to  0 
(xset  b 0). 


Bug  Compatibility  Mode 

Some  Release  3 clients  were  written  to  work  with  “features”  of  the  Release  3 server,  which 
could  more  accurately  be  called  bugs.  Many  of  these  bugs  have  been  eliminated  in  Release 
4.  In  order  to  allow  certain  Release  3 clients  to  work  under  the  Release  4 server,  the  Release 
4 server  has  a bug  compatibility  mode  that  can  be  enabled  using  xset.  In  this  mode,  the 
Release  4 server  is  compatible  with  Release  3 clients  that  depended  on  bugs  in  the  Release  3 
server  to  work  properly  (most  notably  the  Release  3 version  of  xterm ). 

To  enable  bug  compatibility  mode,  use  the  command  xset  be;  to  disable  it,  use  the  com- 
mand xset  -be. 


Keyclick  Volume 

The  c option  sets  the  volume  of  the  keyboard’s  keyclick  and  takes  the  form: 
c volume 

vol  ume  can  be  a value  from  0 to  100,  indicating  a percentage  of  the  maximum  volume.  For 
example: 

% xset  c 75 

sets  a moderately  loud  keyclick.  The  X server  sets  the  volume  to  the  nearest  value  that  the 
hardware  can  support. 

The  c option  also  accepts  the  parameters  on  or  off.  If  you  specify  xset  c on,  the  sys- 
tem default  for  volume  is  used. 

The  keyclick  can  also  be  turned  off  with  the  option  -c,  or  by  setting  the  volume  parameter  to 
0 (xset  c 0). 

On  some  hardware,  a volume  of  0 to  50  turns  the  keyclick  off,  and  a volume  of  51  to  100 
turns  the  keyclick  on. 
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Enabling  or  Disabling  Auto-repeat 

The  r option  controls  the  keyboard’s  auto-repeat  feature.  (Auto-repeat  causes  a keystroke  to 
be  repeated  over  and  over  when  the  key  is  held  down.)  Usexset  rorxset  r on  to 
enable  key  repeat.  Usexset  -rorxset  r of  f to  disable  key  repeat.  On  some  key- 
boards (notably  Apollo),  only  some  keys  repeat,  regardless  of  the  state  of  this  option. 

Changing  or  Rehashing  the  Font  Path 

As  discussed  in  Chapter  8,  Command  Line  Options , when  a client  is  to  be  displayed  in  a par- 
ticular font,  the  server  by  default  looks  for  the  font  in  three  subdirectories  of 
lusrllib/Xll /fonts:  misc,  75dpi , and  100dpi. 

The  fp  (font  path)  option  of  xset  can  be  used  to  change  the  font  path,  i.e.,  to  direct  the  X 
server  to  search  other  directories  for  fonts  called  by  a client.  The  option  must  be  followed  by 
a directory  or  a comma- separated  list  of  directories,  as  in  the  following  example: 

% xset  fp  /work/andy/fonts, /usr/lib/Xll/newfonts 

To  restore  the  default  font  path,  type: 

% xset  fp  default 

As  discussed  in  Chapter  8,  the  fp  option  with  the  rehash  parameter  causes  the  server  to 
reread  the  fonts.dir  and  fonts. alias  files  in  the  current  font  path.  You  need  to  do  this  every 
time  you  edit  an  alias  file  to  make  the  server  aware  of  the  changes. 

To  make  the  server  aware  of  aliases,  type: 

% xset  fp  rehash 

You  also  have  to  do  this  if  you  add  or  remove  fonts.  See  Appendix  A,  System  Management, 
for  more  information. 

Keyboard  LEDs 

The  led  option  controls  the  turning  on  or  off  of  one  or  all  of  the  keyboard’s  LEDs.  It 
accepts  the  parameters  on  or  off  to  turn  all  of  the  LEDs  on  or  off.  A preceding  dash  also 
turns  all  of  the  LEDs  off  (-led). 

You  can  also  turn  individual  LEDs  on  or  off  by  supplying  a numerical  parameter  (a  value 
between  1 and  32)  that  corresponds  to  a particular  LED.  The  led  option  followed  by  a 
numerical  parameter  turns  that  LED  on.  The  led  option  preceded  by  a dash  and  followed  by 
a numerical  parameter  turns  that  LED  off.  For  example. 

% xset  led  3 

would  turn  LED  #3  on,  while: 

% xset  -led  3 

would  turn  LED  #3  off. 
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Note  that  the  particular  LED  values  may  refer  to  different  LEDs  on  different  hardware. 

Pointer  Acceleration 

The  m (mouse)  option  controls  the  rate  at  which  the  mouse  or  pointer  moves  across  the 
screen.  This  option  takes  two  parameters:  acceleration  and  threshold.  They  must 
be  positive  integers.  (The  acceleration  can  also  be  written  as  a numerator/denominator  com- 
bination separated  by  a 7\  for  example,  5/4.) 

The  mouse  or  pointer  moves  acceleration  times  as  fast  when  it  travels  more  than  the 
threshold  number  of  pixels  in  a short  time.  This  way,  the  mouse  can  be  used  for  precise 
alignment  when  it  is  moved  slowly,  yet  it  can  be  set  to  travel  across  the  screen  by  a flick  of 
the  wrist  when  desired.  If  only  one  parameter  is  given,  it  is  interpreted  as  the  acceleration. 

For  example,  the  command: 

% xset  m 5 10 

sets  the  mouse  movement  so  that  if  you  move  the  mouse  more  than  ten  pixels,  the  mouse  cur- 
sor moves  five  times  as  many  pixels  on  the  screen  as  you  moved  the  mouse  on  the  pad. 

If  no  parameter  or  the  value  default  is  used,  the  system  defaults  will  be  set 

If  you  want  to  change  the  threshold  and  leave  the  acceleration  unchanged,  enter  the  value 
default  for  acceleration. 

Screen  Saver 

X supports  a screen  saver  to  blank  or  randomly  change  the  screen  when  the  system  is  left 
unattended  for  an  extended  period.  This  avoids  the  “bum  in”  that  can  occur  when  the  same 
image  is  displayed  on  the  screen  for  a long  time.  The  s (screen  saver)  option  to  xset  deter- 
mines how  long  the  server  must  be  inactive  before  the  screen  saver  is  started. 

The  s option  takes  two  parameters:  time  and  cycle.  The  screen  goes  blank  if  the  server 
has  not  received  any  input  for  the  time  interval  specified  by  the  time  parameter.  The  con- 
tents of  the  screen  reappear  upon  receipt  of  any  input.  If  the  display  is  not  capable  of  blank- 
ing the  screen,  then  the  screen  is  shifted  a pixel  in  a random  direction  at  time  intervals  set  by 
the  cycle  parameter.  The  parameters  are  specified  in  seconds. 

For  example,  the  command: 

% xset  s 600 

sets  the  length  of  time  before  the  screen  saver  is  invoked  to  600  seconds  (ten  minutes). 

For  a display  not  capable  of  blanking  the  screen,  the  command: 

% xset  s 600  10 

sets  the  length  of  time  before  the  screen  saver  is  invoked  to  ten  minutes  and  shifts  the  screen 
every  ten  seconds  thereafter,  until  input  is  received. 
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The  s option  also  takes  the  parameters: 


default  Resets  the  screen  save  option  to  the  default. 

blank  Turns  on  blanking  and  overrides  any  previous  settings. 

noblank  Displays  a background  pattern  rather  than  blanking  the  screen;  overrides  any 
previous  settings. 


off  Turns  off  the  screen  saver  option  and  overrides  any  previous  settings. 


expose  Allows  window  exposures  (the  server  can  discard  window  contents). 

noexpose  Disables  screen  saver  unless  the  server  can  regenerate  the  screens  without 
causing  exposure  events  (i.e.,  without  forcing  the  applications  to  regenerate 
their  own  windows). 

Color  Definition 

On  color  displays,  every  time  a client  requests  a private  read/write  colorcell,  a new  color  def- 
inition is  entered  in  the  display’s  colormap.  The  p option  sets  one  of  these  colormap  entries 
even  though  they  are  supposed  to  be  private.  The  parameters  are  a positive  integer  identify- 
ing a cell  in  the  colormap  to  be  changed,  and  a color  name: 


p entry_number  color_name 

The  root  window  colors  can  be  changed  on  some  servers  using  xsetroot.  An  error  results  if 
the  map  entry  is  a read-only  color. 


For  example,  the  command: 

% xsot  p 3 blue 

sets  the  third  cell  in  the  colormap  to  the  color  blue,  but  only  if  some  client  has  allocated  this 
cell  read/write. 

The  client  that  allocated  the  cell  is  likely  to  change  it  again  sometime  after  you  try  to  set  it, 
since  this  is  the  usual  procedure  for  allocating  a read/write  cell. 


Help  with  xset  Options 

The  q option  lists  the  current  values  of  all  xset  preferences. 
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xsetroot:  Setting  Root  Window  Characteristics 


You  can  use  the  xsetroot  client  to  tailor  the  appearance  of  the  background  (root)  window  on  a 
display  running  X. 

The  xsetroot  client  is  primarily  used  to  specify  the  root  window  pattern:  as  a plaid-like  grid, 
tiled  grey  pattern,  solid  color,  or  a bitmap.  You  can  also  specify  foreground  and  background 
colors  (defaults  are  black  and  white),  reverse  video,  and  set  the  shape  of  the  pointer  when  it’s 
in  the  root  window. 

If  no  options  are  specified,  or  the  -def  option  is  specified,  xsetroot  resets  the  root  window  to 
its  default  state,  a grey  mesh  pattern,  and  resets  the  pointer  to  the  hollow  X pointer.  The 
-def  option  can  also  be  specified  with  other  options;  those  characteristics  that  are  not  set  by 
other  options  are  reset  to  the  defaults. 

Although  xsetroot  can  be  run  any  time,  it  is  suggested  that  you  run  it  from  a startup  shell 
script,  as  described  at  the  end  of  this  chapter.  All  settings  reset  to  the  default  values  when 
you  log  out. 

For  a complete  list  of  options,  see  the  xsetroot  reference  page  in  Part  Three  of  this  guide.  Not 
all  X implementations  are  guaranteed  to  support  all  of  these  options.  Some  of  the  options 
may  not  work  on  certain  hardware  devices. 

The  -help  option  prints  all  the  xsetroot  options  to  standard  output.  The  options  you’ll 
probably  use  most  frequently  are  explained  in  the  next  section.  Since  only  one  type  of  back- 
ground pattern  can  be  specified  at  a time,  the  -solid,  -gray,  -grey,  -bitmap  and 
-mod  options  are  mutually  exclusive. 


Setting  Root  Window  Patterns 

The  default  root  window  pattern  is  called  a “grey  mesh.”  On  most  displays,  it  is  fairly  dark. 

The  xsetroot  client  allows  you  to  specify  an  alternative  grey  background  with  the  -grey  (or 
-gray)  option.  This  tiled  grey  pattern  is  slightly  lighter  than  the  default  grey  mesh  pattern. 

The  xsetroot  client  also  allows  you  to  create  a root  window  made  up  of  repeated  “tiles”  of  a 
particular  bitmap,  using  the  option: 

-bitmap  filename 

where  filename  is  the  bitmap  file  to  be  used  as  the  window  pattern. 

You  can  choose  any  of  the  bitmaps  in  the  directory  I usr I include  1X1 1 /bitmaps  or  make  your 
own  bitmap  files  using  the  bitmap  client  (see  Chapter  7,  Other  Clients). 

For  example,  the  command: 

% xsetroot  -bitmap  /usr/andy/gumby  -fg  red  -bg  blue 

fills  the  root  window  with  a tiling  of  the  bitmap  /usr/andy/gumby  (a  virtual  army  of  Gum- 
bys!),  using  the  colors  red  and  blue. 
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The  mod  option  sets  a plaid-like  grid  pattern  on  the  root  window.  You  specify  the  horizon- 
tal (x)  and  vertical  (y)  dimensions  in  pixels  of  each  square  in  the  grid.  The  syntax  of  the 
option  is: 

-mod  x y 


where  the  parameters  x and  y are  integers  ranging  from  1 to  16  (pixels).  (Zero  and  negative 
numbers  are  taken  as  1.) 

The  larger  the  x and  y values  you  specify,  the  larger  (and  more  visible)  each  square  on  the 
root  window  grid  pattern.  Try  the  command: 

% xsatroot  -mod  16  16 

for  the  largest  possible  grid  squares.  Then  test  different  x and  y specifications. 

The  xsetroot  option: 

—solid  color 

sets  the  color  of  the  root  window  to  a solid  color.  This  can  be  a color  from  the  color  name 
database  or  a more  exact  color  name  specified  by  its  RGB  value. 

The  command: 

% xsetroot  -solid  lightblue 

sets  the  color  of  the  root  window  to  light  blue.*  See  Chapter  8,  Command  Line  Options , for 
more  information  on  how  to  specify  colors. 


Foreground,  Background  Color  and  Reverse  Video 


In  addition  to  specifying  a solid  color  for  the  root  window  pattern,  xsetroot  allows  you  to 
specify  foreground  and  background  colors  if  you  set  the  pattern  with  -bitmap  or  -mod. 
The  standard  Toolkit  options  are  used  to  set  foreground  and  background  colors:  -fg  and 
-bg.  The  defaults  are  black  and  white. 

Colors  can  be  specified  as  names  from  the  color  name  database,  or  as  RGB  values.  See 
Chapter  8 for  more  instructions  on  how  to  specify  color. 

If  you  specify  reverse  video  (-rv),  the  foreground  and  background  colors  are  reversed. 


*For  technical  reasons,  colors  set  with  xsetroot  -solid  may  change  on  you  unexpectedly.  When  you  set  a 
color  with  the  -solid  option  to  xsetroot,  the  client  allocates  a colorcell,  sets  the  color,  and  deallocates  the  colorcell. 
The  root  window  changes  to  that  color.  If  another  client  is  started  that  sets  a new  color,  it  allocates  the  next  available 
colorcell — which  may  be  the  same  one  xsetroot  just  deallocated.  This  results  in  that  color  changing  to  the  new  color. 
The  root  window  also  changes  to  the  new  color.  If  this  happens,  you  can  run  xsetroot  again  and  if  there  are  other 
colorcells  available,  the  root  window  changes  to  the  new  color.  If  all  colorcells  are  allocated,  any  call  to  change  a 
colorcell  results  in  an  error  message. 

While  this  behavior  may  seem  to  be  a vicious  bug,  it  is  actually  an  optimization  designed  to  make  sure  applications 
don’t  run  out  of  colors  unnecessarily.  Free  colormap  cells  can  be  a scarce  resource.  See  Volume  One,  Xlib  Program- 
ming Manual,  for  more  information. 
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Foreground  and  background  colors  also  take  effect  when  you  set  the  root  window  pointer,  as 
described  in  the  following  section. 


Changing  the  Root  Window  Pointer 

By  default,  the  pointer  is  an  X when  it’s  in  the  root  window.  You  can  change  the  shape  of  the 
root  window  pointer  to  one  of  the  standard  X cursor  shapes  or  to  any  bitmap,  using  the  fol- 
lowing options: 

-cursorname  standard_cursor_name 
-cursor  cursor file  maskfile 

Available  as  of  Release  4,  the  first  option  allows  you  to  set  the  root  window  pointer  to  one  of 
the  standard  cursor  symbols,  which  are  generally  listed  in  the  file  lusr/include/Xl  1 Icursor- 
font.h.  We’ve  provided  a list  of  the  standard  cursors  in  Appendix  D.  To  specify  a standard 
cursor  on  a command  line  or  in  a resource  file,  strip  the  XC_  prefix  from  the  name.  Thus,  to 
set  the  root  window  pointer  to  the  pirate  cursor  symbol,  you  would  enter: 

% xs«troot  -cur«or_nan»  pirat® 

If  you  are  running  the  Release  3 version  of  xsetroot,  you  have  to  use  a more  roundabout 
method  to  set  the  root  window  pointer  to  one  of  the  standard  cursor  shapes.  You  must  first 
convert  the  cursor  character  you  want  to  a bitmap,  using  the  atobm  client,  described  in  Chap- 
ter 6,  Graphics  Utilities.  Then  you  can  specify  the  bitmap  as  the  root  window  cursor  shape 
using  the  xsetroot  option  described  in  the  following  paragraphs. 

This  second  option  is  intended  to  allow  you  to  set  the  root  window  pointer  to  a bitmap,  per- 
haps one  you  create.  The  parameters  cursor  file  and  maskfile  are  bitmaps.  The 
cursorfile  sets  the  bitmap  for  the  pointer  shape.  In  effect,  the  maskfile  is  placed 
behind  the  cursorfile  bitmap  to  set  it  off  from  the  root  window.  The  maskfile 
should  be  the  same  shape  as  the  cursorfile , but  should  generally  be  at  least  one  pixel 
wider  in  all  directions.* 

For  the  cursorfile,  you  can  use  any  of  the  standard  bitmaps  in  lusrlincludelXl  1 /bitmaps 
or  you  can  make  your  own  with  the  bitmap  client  (see  Chapter  6,  Graphics  Utilities). 

Every  standard  cursor  has  an  associated  mask.  Pictures  of  the  cursors  appear  in  Appendix  D, 
Standard  Cursors.  To  get  an  idea  of  what  masks  look  like,  display  the  cursor  font  using  the 
command: 

% xfd  -fn  cursor. 

If  you  are  using  your  own  bitmap  as  the  cursorfile,  until  you  get  used  to  the  way  masks 
work,  create  a maskfile  that  is  a copy  of  the  cursorfile  with  all  bits  set,  i.e.,  the 

"■Technically  speaking,  the  mask  determines  the  pixels  on  the  screen  that  are  disturbed  by  the  cursor.  It  functions  as  a 
sort  of  outliner  or  highlighter  for  the  cursor  shape.  The  mask  appears  as  a white  (or  background  color)  border  around 
the  cursor  (black  or  another  foreground  color),  making  it  visible  over  any  root  window  pattern.  This  is  especially  im- 
portant when  a black  cursor  appears  on  a black  root  window. 

With  the  xsetroot  defaults,  you  can  observe  the  effect  of  a mask.  When  you  move  the  X pointer  onto  the  dark  grey 
root  window,  the  X should  have  a very  thin  white  border,  which  enables  you  to  see  it  more  clearly. 
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mask  file  should  be  all  black*  (or  the  foreground  color).  Then  edit  the  mask  file  to 
make  it  wider  than  the  cursorfile  by  at  least  one  pixel  in  all  directions. 

To  specify  a root  window  pointer  made  from  the  smiling  Gumby  bitmap  we  created  for  Fig- 
ure 6-2,  first  copy  the  bitmap  to  make  a mask  file: 

% cp  gumby  gumby. mask 

Then  edit  the  gumby. mask  file  using  the  bitmap  client,  setting  all  squares  inside  the  Gumby. 
(You  can  use  the  bitmap  command  box  Flood  Fill  to  set  all  the  empty  squares  at  once.)  Con- 
tinue to  edit  the  bitmap,  making  it  one  pixel  wider  in  all  directions. 

Then  specify  the  new  pointer  with  xsetroot : 

% xsetroot  -cursor  gumby  gumby. mask 
See  Chapter  6,  Graphics  Utilities,  for  more  information  on  using  bitmap. 


xmodmap:  Modifier  Key  and  Pointer  Customization 

The  xmodmap  client  is  used  to  assign  (or  map)  key  functions  to  physical  keys  on  the  key- 
board. Primarily,  xmodmap  is  used  to  assign  so-called  “modifier”  key  functions  to  physical 
keys,  but  it  can  also  change  the  way  other  keys  (and  even  pointer  buttons)  function. 

As  described  in  Chapter  2,  Getting  Started,  keys  with  labels  such  as  Shift,  Control,  Caps 
Lock,  etc.  are  called  “modifier”  keys  because  they  modify  the  action  of  other  keys.  The 
number  and  names  of  modifier  keys  differ  from  workstation  to  workstation.  Every  keyboard 
is  likely  to  have  a Shift,  Caps  Lock,  and  Control  key,  but  after  that,  the  babble  begins.  One 
workstation  might  have  an  Alt  key,  another  might  have  a Funct  key,  and  yet  another  a “Gold” 
key.  On  the  Sun-3  keyboard,  there  are  no  less  than  three  additional  modifier  keys,  labeled 
Alternate,  Right,  and  Left. 

Because  of  the  differences  between  keyboards,  X programs  are  designed  to  work  with  “logi- 
cal” modifier  keynames.  The  logical  keynames  represent  functions  recognized  by  X pro- 
grams. These  modifier  keynames  can  be  mapped  by  the  user  to  any  physical  key  on  the  key- 
board with  the  xmodmap  client. 

The  logical  keynames  that  X recognizes  are: 

• Shift 

• Lock 

• Ctrl 

• Modi  (also  meta  or  1 in  uwm) 

• Mod2  (also  2 in  uwm ) 


♦Don’t  be  confused  by  the  idea  of  a black  cursor  with  a black  mask  on  a black  root  window.  Remember,  the  mask 
determines  the  pixels  that  are  disturbed  by  the  cursor— in  effect  creating  an  outline  around  the  cursor.  The  outline 
appears  in  white  (or  specified  background  color),  regardless  of  the  color  of  the  ma  sk  fi  1 e. 
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• Mod3  (also  3 in  uwm ) 

• Mod4  (also  4 in  uwm) 

• Mod5  (also  5 in  uwm) 

These  keynames  are  case  insensitive. 

Of  these  X modifier  keys,  only  Shift,  Caps  Lock,  Control,  and  Meta  are  in  common  use.  Note 
that  uwm  also  recognizes  the  mod  keys  simply  by  number  alone  (1-5)  and  recognizes  modi 
as  meta  (i.e.,  modi,  meta  and  1 are  equivalent). 

The  primary  function  of  xmodmap  is  to  allow  you  to  assign  these  important  modifier  key- 
name functions  (Shift,  Control,  Meta,  etc.)  to  convenient  keys  on  the  keyboard.  For 
example,  you  could  choose  to  map  the  Shift  function  to  a single  key  called  “Shift,”  to  two 
“Shift”  keys  (one  on  either  side  of  the  keypad),  to  an  “Alt”  key,  or  to  any  other  convenient 
key  or  keys  on  the  physical  keyboard.  A left-handed  person  might  choose  to  map  modifier 
keys  on  the  right  side  of  the  keyboard  that  more  often  are  found  on  the  left  side,  such  as  Con- 
trol. 

In  practical  terms,  each  server  will  have  a default  keyboard  configuration.  The  Shift,  Caps 
Lock,  and  Control  modifier  keynames  will  be  mapped  to  obvious  keys.  The  assignment  of 
the  Meta  key  might  be  less  obvious. 

The  xmodmap  client  allows  you  to  print  out  the  current  assignments  of  modifier  keyname 
functions  to  physical  keys  and/or  to  change  the  assignments. 

xmodmap  also  has  two  other  functions,  which  you  will  probably  use  less  frequently.  In  addi- 
tion to  mapping  modifier  keyname  functions  to  physical  keys,  xmodmap  also  allows  you  to 
assign  the  function  of  any  key  on  the  keyboard  to  any  other  key.  For  instance,  you  can  make 
the  Backspace  key  and  the  Delete  key  both  function  as  Delete  keys.  (This  may  be  helpful  if 
the  Backspace  key  is  easier  to  reach.) 

Also,  in  addition  to  keyboard  mappings,  xmodmap  can  be  used  to  display  or  change  the 
pointer  button  assignments.  Many  X clients  recognize  logical  pointer  button  commands.  For 
example,  holding  down  and  dragging  the  first  logical  pointer  button  in  an  xterm  window 
copies  the  text  into  memory.  (In  many  default  pointer  maps,  the  first  logical  button  is  the 
leftmost  button,  designed  to  be  pressed  by  the  right  index  finger.)  Each  logical  button  is  asso- 
ciated with  a button  code.  The  first  logical  button  generates  button  code  1,  the  second  logical 
button  generates  button  code  2,  etc.  xmodmap  allows  you  to  reassign  logical  buttons  to  dif- 
ferent physical  buttons  on  the  pointer. 

Thus,  basically,  xmodmap  can  perform  three  types  of  mappings: 

1.  Assign  modifier  keyname  functions  (such  as  Shift,  Control,  Meta)  recognized  by  X to 
physical  keys. 

2.  Make  any  key  on  the  keyboard  function  as  any  other  key  (for  example,  making  Back- 
space function  like  Delete). 

3.  Reassign  logical  pointer  button  functions  to  other  physical  buttons  (for  example,  making 
the  third  physical  button  function  as  the  first  logical  button). 
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In  the  following  sections,  we  discuss  key  mapping,  with  an  emphasis  on  the  first  type  of  map- 
ping, of  modifier  keyname  functions.  Chances  are,  you’ll  have  relatively  little  call  to  map 
other  key  functions  (such  as  Backspace),  though  we  have  included  an  example  of  one  such 
mapping,  just  in  case. 

After  considering  key  mapping,  we’ll  take  a look  at  the  much  simpler  issues  involved  in  map- 
ping pointer  button  functions.  As  you  might  expect,  when  you’re  changing  the  functionality 
of  (up  to)  three  pointer  buttons,  it’s  fairly  simple  to  keep  track  of  what  you’re  doing. 

On  the  other  hand,  mapping  modifier  key  functions  to  physical  keys  can  be  more  than  a little 
confusing.  In  order  to  understand  the  mechanics  of  mapping  keys,  we  first  need  to  take  a 
look  at  some  terms  used  to  describe  keyboard  keys. 

Keycodes  and  Keysyms 

Each  key  on  a physical  keyboard  can  be  identified  by  a number  known  as  a key  code.  (Tech- 
nically speaking,  a keycode  is  the  actual  value  that  the  key  generates.)  Keycodes  cannot  be 
mapped  to  other  keys.  No  matter  what  functions  you  assign  to  various  keys  with  xmodmap, 
the  keycode  associated  with  each  physical  key  remains  the  same. 

In  addition  to  a keycode,  each  physical  key  is  associated  with  a name  known  as  a keysym.  A 
keysym  (“key  symbol”  name)  is  a name  that  represents  the  label  on  a key  (theoretically)  and 
corresponds  to  its  function. 

Alphanumeric  keys  generally  have  obvious  keysyms,  corresponding  to  the  label  on  the  key: 
for  example,  the  keysym  for  the  key  labeled  “H”  is  h.  Unfortunately,  a keysym  does  not 
always  correspond  to  the  key  label.  For  example,  on  a Sun-3  workstation,  though  the  keysym 
for  the  key  labeled  “Return”  is  Return , the  keysym  for  the  key  labeled  “Alternate”  is  Break, 
and  the  keysym  for  the  key  labeled  “Right”  is  MetaR. 

While  each  keycode  is  tied  to  a physical  key,  each  keysym  corresponds  to  a function — and 
the  keysym/function  is  mapped  to  a particular  physical  key  (keycode).  Every  keyboard  has  a 
default  assignment  of  keysyms  to  keycodes.  In  most  cases,  each  physical  key  on  the  key- 
board will  be  associated  with  a different  keysym.  As  we’ll  see,  however,  the  keysym  (func- 
tion) associated  with  a particular  physical  key  (keycode)  can  be  changed.  This  is  done  by 
assigning  the  keysym  of  one  key  to  the  keycode  of  another. 

The  modifier  keynames  recognized  by  X are  not  to  be  confused  with  keysyms.  The  X modi- 
fier keys  are  limited  to  the  eight  keynames  discussed  previously  and  are  assigned  in  addition 
to  the  regular  keysym/keycode  pairings.  In  other  words,  when  a physical  key  is  mapped  to 
function  as  the  X Control  key,  it  already  has  a default  functionality  (keysym)  and  keycode. 

By  default,  most  modifier  keyname  functions  are  mapped  to  keys  having  keysyms  represent- 
ing the  same  function.  For  example,  the  X Control  keyname  is  probably  mapped  to  the  key 
labeled  Control,  and  having  the  keysym  Control. 

The  Meta  modifier  keyname  is  probably  also  assigned  to  a key  having  the  keysym  Meta. 
However,  determining  which  physical  key  has  the  keysym  Meta  can  be  something  of  a 
puzzle.  Later  in  this  chapter,  we’ll  consider  a program  called  xev,  which  can  be  used  to 
determine  the  keysym  and  keycode  of  any  physical  key. 


Setup  Clients 


229 


Setup  Clients 


With  this  background  information  in  mind,  we  can  now  tackle  a procedure  to  map  modifier 
keynames. 


Procedure  to  Map  Modifier  Keys 

In  order  to  change  modifier  key  mappings  with  a minimum  of  confusion,  you  should  perform 

the  following  steps: 

1 . Display  the  current  modifier  key  mappings  using  xmodmap. 

2.  Then  print  out  the  default  assignments  of  keysyms  to  keycodes  for  all  keys,  using  xmod- 
map with  the  -pk  option.  Save  this  list  of  the  default  key  assignments  as  a reference. 

3.  Experiment  with  the  xev  client  to  determine  the  keysyms  associated  with  certain  physical 
keys.  This  will  help  you  find  the  key(s)  assigned  as  the  Meta  modifier  key  (which  proba- 
bly also  has  the  keysym  Meta). 

4.  Once  you’re  familiar  with  the  current  assignments,  you  can  remap  modifier  keys  using 
xmodmap. 


Displaying  the  Current  Modifier  Key  Map 


Before  mapping  any  modifier  keynames,  you  should  take  a look  at  the  current  assignments. 
With  no  options,  xmodmap  displays  the  current  map  of  X modifier  keynames  to  actual  keys. 
Type  xmodmap  and  you  get  a display  similar  to  this: 


xmodmap:  up  to  2 keys  per  modifier,  (keycodes  in  parentheses): 


shift 

lock 

control 

modi 

mod2 

mod3 

mod4 

mod5 


ShiftL  (0x6a) , Shift_R  (0x75) 
CapsLock  (0x7e) 

ControlL  (0x53) 

MetaL  (0x7f) , Meta_R  (0x81) 


For  each  logical  keyname  (on  the  left),  xmodmap  lists  one  or  more  keysyms,  each  followed  in 
parentheses  by  an  actual  hardware  keycode.  The  keycodes  displayed  by  xmodmap  are  repre- 
sented in  hex.  As  we’ll  see,  the  equivalent  decimal  and  octal  keycodes  are  also  accepted  as 
arguments  to  xmodmap. 
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"Logical"  modifier  keyname 
recognized  by  X 

Keysym 

Keycode 
(hex  version) 

Shift 

Shift_L 

Shift_R 

(0x6a) 

(0x75) 

Lock 

Caps_Lock 

(0x7e) 

Control 

Control_L 

(0x53) 

Modi 

MetaJL 

Meta_R 

(0x7f) 

(0x81) 

In  this  mapping,  two  keys  are  assigned  as  Meta  (modi)  keys:  keys  having  the  keysyms 
Meta_L  and  Meta_R  (for  left  and  right,  apparently  one  on  each  side  of  the  keyboard).  Unfor- 
tunately, as  you  can  see,  this  doesn’t  really  tell  you  which  keys  these  are  on  the  physical  key- 
board. You  still  need  to  know  which  physical  keys  (keycodes)  have  the  keysyms  Meta_L  and 
Meta_R.  You  can  determine  this  using  the  xev  client,  described  later  in  this  chapter. 

Determining  the  Default  Key  Mappings 

Before  you  start  mapping  keys,  you  should  display  and  save  a map  of  the  default  assignments 
of  keysyms  to  keycodes.  Running  xmodmap  with  the  -pk  option  prints  a current  map  of  all 
keyboard  keys  to  standard  output  This  map,  called  a keymap  table,  lists  the  decimal  key- 
code  on  the  left  and  the  associated  keysym(s)  on  the  right.  Figure  11-1  shows  a portion  of  a 
typical  keymap  table,  for  a Sun-3  keyboard. 

Notice  that  each  keysym  is  listed  by  a keysym  name  (comma,  Caps_Lock,  etc.)  and  a keysym 
value  (0x002c,  0xffe5,  etc).  For  our  purposes,  this  value  is  irrelevant.  It  cannot  be  supplied 
as  a keysym  argument  to  xmodmap. 

As  you  can  see,  the  keymap  table  lists  regular  keyboard  keys  (C,  V,  comma,  slash,  space, 
etc.),  and  function/numeric  keypad  keys  (R13,  F35,  etc.)  as  well  as  modifier  keys 
(Caps_Lock,  Meta_L  and  Meta  _R).  If  you  map  several  keys,  you  may  get  confused  as  to  the 
original  assignments.  Before  you  map  any  keys,  we  suggest  you  redirect  the  keymap  table  to 
a file  to  save  and  use  as  a reference: 

% xmodmap  -pk  > keytable 

The  keysyms  recognized  by  your  server  are  a subset  of  a far  greater  number  of  keysyms 
recognized  internationally.  The  file  lusrlinclude/Xl  1 Ikeysym.h  lists  the  keysym  families  that 
are  enabled  for  your  server.  The  file  I usr linclu.de/Xl  1 Ikeysymdef.h  lists  the  keysyms  in  each 
of  the  families  enabled  for  your  server,  as  well  as  the  keysyms  in  several  other  families.  See 
Appendix  H,  Keysyms,  of  Volume  Two,  Xlib  Reference  Manual,  for  more  information  on 
keysyms  and  tables  of  the  most  common  ones. 
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Keycode 

Keysym 

value 

(name) 

109 

0x0043 

(C) 

110 

0x0056 

(V) 

111 

0x0042 

(B) 

112 

0x004e 

(N) 

113 

0x004d 

(M) 

114 

0x002c 

(comma)  0x003c 

(less) 

115 

0x002e 

(period)  0x003e 

(greater) 

116 

0x002f 

(slash)  0x003f 

(question ) 

117 

0xffe2 

( Shif t_R) 

118 

OxffOa 

(Linefeed) 

119 

Oxf f de 

(R13) 

120 

Oxf f 54 

(Down)  Oxffdf 

(F34  ) 

121 

Oxf f eO 

(F35) 

126 

Oxf f e5 

(Caps  Lock) 

127 

Oxf fe7 

(MetaL) 

128 

0x0020 

(space) 

129 

Oxf fe8 

(Meta  R) 

Figure  11-1.  Partial  key  map  table 


Matching  Keysyms  with  Physical  Keys  Using  xev 

The  keysym  and  keycode  for  any  key  can  be  determined  with  the  xev  client.*  This  is  particu- 
larly useful  for  finding  the  Meta  key(s).  The  xev  client  is  used  to  keep  track  of  events,  pack- 
ets of  information  that  are  generated  by  the  server  when  actions  occur  and  are  interpreted  by 
other  clients.  Moving  the  pointer  or  pressing  a keyboard  key  cause  input  events  to  occur. 
(For  more  information  about  events,  see  Volume  One,  Xlib  Programming  Manual.) 

To  use  xev,  enter  the  command: 

% xev 

in  an  xterm  window,  and  then  use  the  pointer  to  place  the  xev  window,  as  in  Figure  11-2. 

Within  the  xev  window  is  a small  box.  Move  the  pointer  inside  this  box.  When  you  type  a 
key  inside  the  box,  information  about  the  key,  including  its  keysym  and  keycode,  will  be 
displayed  in  the  xterm  window  from  which  you  started  xev.  The  relevant  information  will 
look  like  this: 


*xev  is  a Release  3 standard  client.  In  Release  4,  it  has  been  moved  to  the  demos  directory.  If  an  executable  version 
does  not  exist  on  your  system,  ask  your  system  administrator. 

If  you  cannot  use  xev,  you  must  rely  on  the  keymap  table  and  a little  deductive  reasoning.  Since  certain  twm  func- 
tions have  keyboard  shortcuts  involving  the  Meta  key,  testing  these  shortcuts  should  help  you  locate  this  key.  See 
Chapter  3,  Using  the  twm  Window  Manager,  for  more  information. 
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Figure  11-2.  xev  window 

. . . keycode  127  (keysym  0xffe7,  Meta_L)  . . 

Notice  that  the  keycode  is  given  as  a decimal  number.  You  can  use  the  decimal  keycode  as 
an  argument  to  xmodmap.  The  keysym  is  listed  by  name,  Meta_L,  and  value,  0xffe7.  Again, 
this  value  cannot  be  supplied  as  a keysym  argument  to  xmodmap . (See  the  xev  reference 
page  in  Part  Three  for  more  information.) 

To  find  the  Meta  key,  type  a few  likely  keys  in  the  xev  window.  Type  Control-C  in  the  win- 
dow from  which  you  invoked  xev  to  terminate  the  program.  (If  you  ran  xev  in  the  back- 
ground, you’ll  have  to  kill  the  xev  window.  See  Chapter  7,  Other  Clients , for  ways  to  do 
this.) 


Changing  the  Map  with  xmodmap 


xmodmap  executes  an  expression  or  list  of  expressions  that  are  interpreted  as  instructions  to 
modify  the  key  (or  pointer)  map.  The  expressions  that  can  be  interpreted  by  xmodmap  are 
described  in  the  next  section. 

xmodmap  has  the  following  syntax: 

xmodmap  [options]  [filename] 

An  expression  can  be  executed  in  either  one  of  two  ways: 

• From  the  command  line,  using  the  -e  expression  option.  This  option  specifies  an 
expression  to  be  executed  (as  an  instruction  to  modify  the  map).  Any  number  of  expres- 
sions may  be  specified  from  the  command  line.  An  expression  should  be  enclosed  in 
quotes. 

• Entered  in  a file  that  is  used  as  an  argument  to  xmodmap.  Several  expressions  can  be 
entered  in  one  file. 
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See  the  xmodmap  reference  page  in  Part  Three  of  this  guide  for  a complete  list  of  options. 
Other  than  -e  express i on,  the  most  important  options  for  our  purposes  are  listed  below. 

-n  Indicates  that  xmodmap  should  not  change  the  key  mappings  as  specified  in 

the  filename  or  command  line  expression,  but  should  display  what  it 
would  do.  A handy  test.  (Only  works  with  key  mappings,  not  with  expres- 
sions that  change  the  pointer  map.) 

-verbose  Indicates  that  xmodmap  should  print  logging  information  as  it  parses  its 
input. 

filename  specifies  a file  containing  xmodmap  expressions  to  be  executed  (as  instructions 
to  modify  the  map).  This  file  is  usually  kept  in  the  user’s  home  directory  with  a name  like 
.xmodmaprc. 

Expressions  to  Change  the  Key  Map 

The  expressions  interpreted  by  xmodmap  can  be  used  to  perform  the  following  types  of  key 
mappings:* 

1.  Assign  and  remove  keysyms  as  modifier  keynames  recognized  by  X. 

2.  Map  any  keysym  (function)  to  any  physical  key  (keycode). 

The  following  list  shows  allowable  expressions,  divided  by  function.  (Using  xmodmap  with 
the  -grammar  option  returns  a help  message  with  much  of  this  information.)  Those  expres- 
sions that  include  an  equal  sign  require  a space  before  and  after  the  sign. 

1.  To  assign  and  remove  keysyms  as  modifier  keynames: 

Clear  MOD I FIER NAME 

Removes  all  entries  in  the  modifier  map  for  the  given  modifier,  where  valid  mod- 
ifier names  are:  shift,  lock,  control,  modi,  mod2,  mod3,  mod4,  and  mod5  (case 
does  not  matter  in  modifier  names,  although  it  does  matter  for  all  other  names). 
For  example,  the  expression  clear  Lock  will  remove  all  keys  that  were 
bound  to  the  lock  modifier. 

add  MODIFIERNAME  = KEYSYMNAME 

Adds  the  given  keysym  to  the  indicated  modifier  map.  For  example,  you  could 
make  the  Alt  key  an  additional  shift  modifier  key.  The  keysym  name  is 
evaluated  after  all  input  expressions  are  read  to  make  it  easy  to  write  expressions 
to  swap  keys. 

remove  MODIFIERNAME  = KEYSYMNAME 

Removes  the  given  keysym  from  the  indicated  modifier  map  (unmaps  it).  For 
example,  remove  CapsJLock  as  the  lock  modifier  key.  Unlike  with  the  add 

♦Expressions  to  change  the  pointer  map  are  discussed  in  the  section  Displaying  and  Changing  the  Pointer  Map,  later 
in  this  chapter. 
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expression,  the  keysym  names  are  evaluated  as  the  line  is  read  in.  This  allows 
you  to  remove  keys  from  a modifier  without  having  to  worry  about  whether  or 
not  they  have  been  reassigned. 

2.  To  map  any  keysym(s)  to  any  physical  key  (keycode): 

key code  NUMBER  = KEYSYMNAME 

Assigns  the  keysym  to  the  indicated  keycode  (which  may  be  specified  in  deci- 
mal, hex  or  octal).  Usually  only  one  keysym  is  assigned  to  a given  code. 

keysym  KEYSYMNAME  = KEYSYMNAME 

Assigns  the  keysym  on  the  right  to  the  keycode  of  the  keysym  on  the  left.  Note 
that  if  you  have  the  same  keysym  bound  to  multiple  keys,  this  might  not  work. 

Key  Mapping  Examples 

Expressions  can  be  used  on  the  xmodmap  command  line  or  entered  in  a file  that  is  then  used 
as  an  argument  to  xmodmap.  Note  that  xmodmap  should  be  run  from  your  startup  script  (dis- 
cussed later  in  this  chapter)  to  take  effect  for  all  clients  in  the  login  session.  This  section 
includes  three  examples,  corresponding  to  the  three  types  of  mappings  you  can  perform. 

Remember  that  including  the  -n  option  on  the  xmodmap  command  line  allows  you  to  see 
what  the  new  mappings  would  be,  without  actually  performing  them.  This  can  be  very  use- 
ful, particularly  while  you’re  learning  to  use  xmodmap  and  getting  used  to  the  syntax  of 
expressions.  (Note,  however,  that  -n  cannot  be  used  with  expressions  to  change  the  pointer 
mapping.) 

First,  the  xmodmap  client  also  allows  you  to  assign  logical  modifier  keynames  to  physical 
keys.  A not  so  obvious  feature  of  xmodmap  is  that  to  change  the  mapping  of  a modifier  key, 
you  must  first  remove  that  key  from  the  current  modifier  map.  For  example,  to  swap  the  left 
Control  and  (Caps)  Lock  keys,  you  would  first  need  to  unmap  both  physical  keys 
(Caps_Lock,  Control_L)  from  their  respective  modifier  keynames  (lock,  control): 


remove  lock  = Caps_Lock 
remove  control  = Control  L 


And  then  reverse  the  mappings: 

add  lock  = Control_L 
add  control  = Caps_Lock 


If  you  then  type  xmodmap  without  options,  you  see  the  new  map: 


xmodmap:  up  to  2 keys  per  modifier. 


(keycodes 


in  parentheses) : 


shift 

lock 

control 

modi 

mod2 

mod3 

mod4 

mod5 


Shift_L  (0x6a) , Shift_R  (0x75) 
Control_L  (0x53) 

Caps_Lock  (0x7e) 

Meta  L (0x7f) , Meta_R  (0x81) 
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The  key  with  the  keysym  Control_L  functions  as  a Lock  key  and  the  key  with  the  keysym 
Caps_Lock  functions  as  a Control  key. 

Second,  xmodmap  allows  you  to  assign  any  keysym  to  any  other  key.  For  example,  you 
might  make  the  Backspace  key  function  as  a Delete  key: 

% xmodmap  -«  'keysym  Backspace  = Delete' 

Then  when  you  display  the  keymap  table  and  grep  for  the  Delete  keysym,  you’ll  see  that  it  is 
assigned  twice.  On  the  command  line  of  an  xterm  window,  type: 

% xmodmap  -pk  | grep  Delete 

and  you’ll  get  two  lines  from  the  current  keymap  table,  similar  to  these: 

50  Oxffff  (Delete) 

73  Oxffff  (Delete) 

The  50  and  73  are  keycodes  representing  two  physical  keys.  As  you  can  see,  both  of  these 
keys  now  function  as  Delete  keys. 

This  example  suggests  some  of  the  confusion  you  can  experience  using  xmodmap.  We  know 
that  one  of  these  keys  previously  functioned  as  the  Backspace  key.  But  how  can  we  tell 
which  one?  Here  is  an  instance  when  our  default  keymap  table  comes  in  handy.  If  you’ve 
run  xmodmap  -pk  and  redirected  it  to  a file  before  changing  any  mappings,  you  can  check 
the  file  for  the  keysyms  originally  associated  with  the  keycodes  50  and  73.  In  this  case,  the 
file  tells  us  50  was  originally  Backspace  and  73  was  Delete. 

Of  course,  you  could  also  figure  out  the  original  assignments  by  remapping  one  of  the  key- 
codes  to  Backspace.  Then,  if  the  key  marked  Backspace  functions  as  marked,  you  know 
you’ve  mapped  the  keysym  to  the  original  keycode.  But,  as  you  can  see,  the  default  keymap 
table  can  greatly  simplify  matters. 

This  example  also  implies  that  there  are  advantages  to  using  expressions  of  the  form: 

keycode  number  = keysymname 

This  expression  syntax  requires  you  to  be  aware  of  default  keycode/keysym  assignments. 
Also,  if  you  explicitly  assign  a keysym  to  a particular  keycode,  it’s  much  easier  to  keep  track 
of  what  you’re  doing  and  retrace  your  steps  if  necessary.  On  the  down  side,  though  keysyms 
are  portable,  keycodes  may  vary  from  server  to  server.  Thus,  expressions  using  this  syntax 
cannot  be  ported  to  other  systems. 


Displaying  and  Changing  the  Pointer  Map 

If  you  want  to  change  the  assignment  of  logical  pointer  buttons  to  physical  buttons,  you 
should  first  display  the  current  pointer  map  with  the  -pp  option  to  xmodmap.  A typical 
pointer  map  appears  in  Figure  11-3. 

This  is  a fairly  simple  map:  the  physical  buttons  are  listed  on  the  left  and  the  corresponding 
logical  functions  (button  codes)  are  listed  on  the  right. 
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There  are  3 pointer  buttons  defined. 


Physical 

Button 


Button 

Code 


1 

2 

3 


1 

2 

3 


Figure  11-3.  Pointer  map 

These  are  typical  assignments  for  a right-handed  person:  the  first  logical  button  is  the  left- 
most button,  designed  to  be  pressed  by  the  right  index  finger.  The  xmodmap  client  allows 
you  to  reassign  logical  buttons  so  that  the  pointer  can  be  more  easily  used  with  the  left  hand. 

The  xmodmap  client  allows  you  to  change  the  pointer  map.*  There  are  two  xmodmap  expres- 
sions: one  to  assign  logical  pointer  buttons  (button  codes)  to  physical  buttons;  and  another  to 
restore  the  default  assignments.  The  syntax  of  the  expressions  is  as  follows: 

pointer  = x y z 

Sets  the  first,  second,  and  third  physical  buttons  to  the  button  codes  x,  y,  and  z. 
pointer  = default 

Sets  the  pointer  map  back  to  its  default  settings  (button  1 generates  a code  of  1,  but- 
ton 2 generates  a code  of  2,  etc.). 

Being  able  to  change  the  pointer  button  assignments  is  very  useful  if  you  happen  to  be  left- 
handed  and  would  like  the  rightmost  physical  button  to  function  as  the  first  logical  button 
(i.e.,  generate  button  code  1).  To  configure  the  pointer  for  a southpaw: 

% xmodmap  -a  ' pointer  =321' 

Then  if  you  display  the  pointer  mappings  with  xmodmap  -pp,  you  get  the  following: 


There  are  3 pointer  buttons  defined. 


Button 

Code 


Physical 

Button 


3 

2 

1 


1 

2 

3 


You  can  then  push  the  first  logical  button  (button  code  1)  with  the  index  finger  of  your  left 
hand. 

You  can  return  to  the  default  pointer  button  assignments  by  entering: 

% xmodmap  —a  ' pointar  — da fault ' 


* Remember  that  the  -n  option,  which  allows  you  to  see  what  xmodmap  would  do,  without  performing  the  changes, 
cannot  be  used  with  expressions  to  change  the  pointer  mapping. 
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Part  Three 


Client  Reference  Pages 


This  part  of  the  guide  provides  UNIX-style  “ man-pages " for  each  of  the  X pro- 
grams. These  pages  are  arranged  alphabetically  for  ease  of  reference,  and 
they  contain  detailed  information  (such  as  all  options  to  a program)  that  is  not 
covered  in  other  parts  of  this  guide. 


The  following  reference  pages  appear  in  this  section: 


intro 

X 

Xau 

Xserver 

appres 

bdftosnf 

bitmap 

listres 

mkfontdir 

oclock 

resize 

sedscr 

showsnf 

twm 

uwm 

xIOtoxll 

xauth 

xbiff 

xcalc 

xclipboard 

xclock 

xcutsel 

xditview 

xload 

xlogo 

xlsatoms 

xlsclients 

xlsfonts 

xdm 

xdpr 

xdpyinfo 

xedit 

xev 

xfd 

xfontsel 

xhost 

xinit 

xkill 

xlswins 

xmag 

xman 

xmh  (Release  4) 

xmh  (Release  3) 

xmodmap 

xpr 

xprop 

xpseudoroot 

xrdb 

xrefresh 

xset 

xsetroot 

xstdcmap 

xterm 

xwd 

xwininfo 

xwud 

— Introduction 


Intro 


Name 

Intro  - overview  of  reference  page  format. 

Syntax 

This  section  describes  the  command  line  syntax  for  invoking  the  client 

Description 

This  section  explains  the  operation  of  the  client. 

Options 

This  section  lists  available  command  line  options.  In  some  cases,  reference  is  made  to  “all  of 
the  standard  X Toolkit  command  line  options.”  These  X Toolkit  options  are  listed  in  Chapter  8 
of  this  guide. 

Resources 

This  section  lists  the  resource  variable  names  that  can  be  specified  in  an  JCresources  or  other 
resource  file.  In  some  cases,  reference  is  made  to  “all  the  core  resource  names  and  classes.”  A 
list  of  the  core  names  and  classes  appears  on  the  reference  page  for  X and  in  Table  8-1  in  Chap- 
ter 8,  Command  Line  Options.  See  Chapter  9,  Setting  Resources , for  syntax  rules  and 
examples.  For  complete  information,  see  Volume  Four,  X Toolkit  Intrinsics  Programming 
Manual. 

Environment 

If  present,  this  section  lists  shell  environment  variables  used  by  the  client.  This  section  does 
not  list  the  DISPLAY  and  XENVIRONMENT  variables,  which  are  used  by  all  clients.  They  are 
used  as  follows: 

DISPLAY  To  get  the  default  host  and  display  number. 

XENVIRONMENT  To  get  the  name  of  a resource  file  that  overrides  the  global  resources 
stored  in  the  RESOURCE_MANAGER  property. 

See  Also 

This  section  lists  other  pages  in  Part  Three  of  this  guide  that  may  also  be  of  interest.  Note  that 
versions  of  these  pages  may  have  been  installed  in  the  usual  on-line  manual  hierarchy,  and  may 
be  available  via  the  UNIX  man(  1)  command.  References  such  as  stat( 2)  can  be  found  in  the 
standard  UNIX  documentation.  This  section  may  also  include  references  to  documentation  on 
Xlib,  the  X Toolkit,  various  widgets,  etc. 

Bugs 

If  present,  this  section  lists  areas  in  which  the  author  of  the  program  thinks  it  could  be 
improved.  In  a few  cases,  we’ve  added  additional  bugs  we’ve  noted. 

Author 

The  authors  of  the  program  and  (generally)  the  reference  page  as  well.  Most  of  the  reference 
pages  are  subject  to  the  copyright  provisions  in  the  “Copyright”  section  of  the  X reference 
page.  Where  appropriate,  additional  copyrights  are  noted  on  individual  pages. 
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(continued) 


Introduction 


Note,  however,  that  those  portions  of  this  document  that  are  based  on  the  original  XI 1 docu- 
mentation and  other  source  materials  have  been  revised  and  that  all  such  revisions  are  copy- 
right © 1987,  1988,  1989  O’Reilly  & Associates,  Inc.  Inasmuch  as  the  proprietary  revisions 
can’t  be  separated  from  the  freely  copyable  MIT  source  material,  the  net  result  is  that  copying 
of  this  document  is  not  allowed.  Sorry  for  the  doublespeak! 
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Name 

X - a portable,  network  transparent  window  system. 

Description 

X is  a network  transparent  window  system  developed  at  MIT  that  runs  on  a wide  range  of  com- 
puting and  graphics  machines.  The  Release  4 core  distribution  from  MIT  has  support  for  the 
following  operating  systems: 


Ultrix  3.1  (Digital) 

SunOS  4.0.3  (Sun) 

HP-UX  6.5  (Hewlett-Packard) 

Domain/OS  10.1  (HP/Apollo) 

A/UX  1.1  (Apple) 

AIX  RT-2.2  and  PS/2-1.1  (IBM) 

AOS-4.3  (IBM) 

UTEK  4.0  (Tektronix) 

NEWS-OS  3.2  (Sony;  client  only) 

UNICOS  5.0.1  (Cray;  client  only) 

UNIX(tm)  System  V,  Release  3.2  (AT&T  6386  WGS;  client  only) 

It  should  be  relatively  easy  to  build  the  client-side  software  on  a variety  of  other  systems. 
Commercial  implementations  are  also  available  for  a much  wider  range  of  platforms. 

The  X Consortium  requests  that  the  following  names  be  used  when  referring  to  this  software: 

X 

X Window  System 
X Version  1 1 

X Window  System,  Version  1 1 
Xll 

X Window  System  is  a trademark  of  the  Massachusetts  Institute  of  Technology. 

X window  system  servers  run  on  computers  with  bitmap  displays.  The  server  distributes  user 
input  to  and  accepts  output  requests  from  various  client  programs  through  a variety  of  different 
interprocess  communication  channels.  Although  the  most  common  case  is  for  the  client  pro- 
grams to  be  running  on  the  same  machine  as  the  server,  clients  can  be  run  transparently  from 
other  machines  (including  machines  with  different  architectures  and  operating  systems)  as  well. 

X supports  overlapping  hierarchical  sub  windows  and  text  and  graphics  operations,  on  both 
monochrome  and  color  displays.  For  a full  explanation  of  the  functions  that  are  available,  see 
Volume  Four,  X Toolkit  Intrinsics  Programming  Manual  and  Volume  Five,  X Toolkit  Intrinsics 
Reference  Manual. 

The  number  of  programs  that  use  X is  growing  rapidly.  Of  particular  interest  are:  a terminal 
emulator  ( xterm ),  a window  manager  (twm),  a display  manager  (xdm),  mail  managing  utilities 
(xmh  and  xbiff ),  a manual  page  browser  ( xman ),  a bitmap  editor  {bitmap),  access  control 
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programs  ( xauth  and  xhost),  user  preference  setting  programs  (xrdb,  xset,  xsetroot,  and  xmod- 
map),  a load  monitor  (jc load),  clocks  ( oclock  and  xclock ),  a font  displayer  (xfd),  utilities  for  list- 
ing information  about  fonts,  windows,  and  displays  (. xlsfonts , xfontsel,  xlswins,  xwininfo,  xdpy- 
info , xlsclients,  and  xprop ),  a diagnostic  for  seeing  what  events  are  generated  and  when  (xev), 
screen  image  manipulation  utilities  (xwd,  xwud,  xpr , and  xmag),  and  various  demos  ( xeyes , ico, 
muncher,  puzzle , xgc,  etc.). 

Many  other  utilities,  window  managers,  games,  toolkits,  etc.  are  available  from  the  user-contri- 
buted distribution.  See  your  site  administrator  for  details. 

Starting  Up 

There  are  currently  three  ways  of  starting  the  X server  and  an  initial  set  of  client  applications. 
The  particular  method  used  depends  on  what  operating  system  you  are  running  and  on  whether 
or  not  you  use  other  window  systems  in  addition  to  X. 

xdm  (the  X Display  Manager) 

If  you  want  to  always  have  X running  on  your  display,  your  site  administrator 
can  set  your  machine  up  to  use  the  X Display  Manager  xdm.  This  program  is 
typically  started  by  the  system  at  boot  time  and  takes  care  of  keeping  the 
server  running  and  getting  users  logged  in.  If  you  are  running  xdm,  you  will 
see  a window  on  the  screen  welcoming  you  to  the  system  and  asking  for  your 
username  and  password.  Simply  type  them  in  as  you  would  at  a normal  ter- 
minal, pressing  the  Return  key  after  each.  If  you  make  a mistake,  xdm  will 
display  an  error  message  and  ask  you  to  try  again.  After  you  have  success- 
fully logged  in,  xdm  will  start  up  your  X environment.  By  default,  if  you 
have  an  executable  file  named  jcsession  in  your  home  directory,  xdm  will 
treat  it  as  a program  (or  shell  script)  to  run  to  start  up  your  initial  clients  (such 
as  terminal  emulators,  clocks,  a window  manager,  user  settings  for  things  like 
the  background,  the  speed  of  the  pointer,  etc.).  Your  site  administrator  can 
provide  details. 

xinit  (run  manually  from  the  shell) 

Sites  that  support  more  than  one  window  system  might  choose  to  use  the  xinit 
program  for  starting  X manually.  If  this  is  true  for  your  machine,  your  site 
administrator  will  probably  have  provided  a program  named  “xll”,  “startx”, 
or  “xstart”  that  will  do  site-specific  initialization  (such  as  loading  convenient 
default  resources,  running  a window  manager,  displaying  a clock,  and  starting 
several  terminal  emulators)  in  a nice  way.  If  not,  you  can  build  such  a script 
using  the  xinit  program.  This  utility  simply  runs  one  user-specified  program 
to  start  the  server,  runs  another  to  start  up  any  desired  clients,  and  then  waits 
for  either  to  finish.  Since  either  or  both  of  the  user-specified  programs  may 
be  a shell  script,  this  gives  substantial  flexibility  at  the  expense  of  a nice 
interface.  For  this  reason,  xinit  is  not  intended  for  end  users. 

xterm  -L  (started  from  letclinit) 

This  method  can  be  used  only  with  Release  3 (or  an  earlier  release)  of  X. 
Some  versions  of  UNIX  that  are  derived  from  BSD  4.3  support  starting  the 
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window  system  and  an  initial  xterm  window  from  the  system  terminal  line 
configuration  file  /etc/ttys.  As  with  xdm,  there  will  be  a window  requesting 
your  username  and  password.  However,  this  window  will  become  your  pri- 
mary window  and  is  not  configurable  on  a per-user  basis.  Sites  using  this 
method  should  switch  to  xdm  as  xterm  -L  is  not  be  supported  as  of  Release  4. 

Display  Names 

From  the  user  s perspective,  every  X server  has  a display  name  of  the  form: 
host : display . screen 

This  information  is  used  by  the  application  to  determine  how  it  should  connect  to  the  server  and 
which  screen  it  should  use  by  default  (on  displays  with  multiple  monitors): 

host  The  name  of  the  machine  to  which  the  display  is  physically  connected.  If  the 

host  name  is  not  given,  the  most  efficient  way  of  communicating  to  a server 
on  the  same  machine  will  be  used. 

di  spl  ay  The  di  spl  ay  number.  The  phrase  “display”  is  usually  used  to  refer  to  a col- 

lection of  monitors  that  share  a common  keyboard  and  pointer  (mouse,  tablet, 
etc.).  Most  workstations  tend  to  only  have  one  keyboard,  and  therefore,  only 
one  display.  Larger,  multi-user  systems,  however,  will  frequently  have  sev- 
eral displays  so  that  more  than  one  person  can  be  doing  graphics  work  at 
once.  To  avoid  confusion,  each  display  on  a machine  is  assigned  a display 
number  (beginning  at  0)  when  the  X server  for  that  display  is  started.  The 
display  number  must  always  be  given  in  a display  name.  In  this  guide,  the 
display  number  is  also  referred  to  as  the  server  number  (referring  to  the 
phrase  display  server). 

screen  The  screen  number.  Some  displays  share  a single  keyboard  and  pointer 

among  two  or  more  monitors.  Since  each  monitor  has  its  own  set  of  win- 
dows, each  screen  is  assigned  a screen  number  (beginning  at  0)  when  the  X 
server  for  that  display  is  started.  If  the  screen  number  is  not  given,  then 
screen  0 will  be  used. 

On  POSIX  systems,  the  default  display  name  is  stored  in  your  DISPLAY  environment  variable. 
This  variable  is  set  automatically  by  the  xterm  terminal  emulator.  However,  when  you  log  into 
another  machine  on  a network,  you’ll  need  to  set  DISPLAY  by  hand  to  point  to  your  display. 
For  example, 

% setenv  DISPLAY  myws:0 
$ DISPLAY=myws : 0;  export  DISPLAY 

Finally,  most  X programs  accept  a command  line  option  of  -display  displayname  to 
temporarily  override  the  contents  of  DISPLAY.  This  is  most  commonly  used  to  pop  windows  on 
another  person’s  screen  or  as  part  of  a “remote  shell”  command  to  start  an  xterm  pointing  back 
to  your  display.  For  example, 
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% xoyes  -display  joasws : 0 -gaoroatry  1000x1000+0+0 
% rsh  big  xtarm  -display  myws:0  -Is  </dav/null  & 

X servers  listen  for  connections  on  a variety  of  different  communications  channels  (network 
byte  streams,  shared  memory,  etc.).  Since  there  can  be  more  than  one  way  of  contacting  a 
given  server,  the  host  name  part  of  the  display  name  is  used  to  determine  the  type  of  channel 
(also  called  a transport  layer)  to  be  used.  The  sample  servers  from  MIT  support  the  following 
types  of  connections: 

local  The  host  part  of  the  display  name  should  be  the  empty  string.  For  example: 

: 0,  : 1,  and  : 0 . 1. 

TCP/IP  The  host  part  of  the  display  name  should  be  the  server  machine’s  IP  address 

name.  Full  Internet  names,  abbreviated  names,  and  IP  addresses  are  all 
allowed.  For  example:  expo . lcs  .mit  .edu:  0,  expo:0, 

18.30.0.212:0, bigmachine : 1,  and  hydra : 0 . 1. 

DECnet  The  host  part  of  the  display  name  should  be  the  server  machine’s  nodename 

followed  by  two  colons  instead  of  one.  For  example:  myws  : : 0,  big:  : 1, 
and  hydra  : : 0 . 1. 


Access  Control 

The  sample  server  provides  two  types  of  access  control:  an  authorization  protocol  that  pro- 
vides a list  of  “magic  cookies”  clients  can  send  to  request  access  (available  as  of  Release  4); 
and  a list  of  hosts  from  which  connections  are  always  accepted,  xdm  initializes  magic  cookies 
in  the  server,  and  also  places  them  in  a file  accessible  to  the  user.  Normally,  the  list  of  hosts 
from  which  connections  are  always  accepted  should  be  empty,  so  that  only  clients  that  are 
explicitly  authorized  can  connect  to  the  display.  When  you  add  entries  to  the  host  list  (with 
xhost),  the  server  no  longer  performs  any  authorization  on  connections  from  those  machines. 
Be  careful  with  this. 

The  file  for  authorization  used  by  both  xdm  and  Xlib  can  be  specified  with  the  environment 
variable  XAUTHORITY,  and  defaults  to  the  file  Xauthority  in  the  home  directory,  xdm  uses 
$HOMEI Xauthority  and  will  create  it  or  merge  in  authorization  records  if  it  already  exists 
when  a user  logs  in. 

To  manage  a collection  of  authorization  files  containing  a collection  of  authorization  records, 
use  xauth.  This  program  allows  you  to  extract  records  and  insert  them  into  other  files.  Using 
this,  you  can  send  authorization  to  remote  machines  when  you  login.  As  the  files  are  machine- 
independent,  you  can  also  simply  copy  the  files  or  use  NFS  to  share  them.  If  you  use  several 
machines,  and  share  a common  home  directory  with  NFS,  then  you  never  really  have  to  worry 
about  authorization  files,  the  system  should  work  correctly  by  default.  Note  that  magic  cookies 
transmitted  “in  the  clear”  over  NFS  or  using///?  or  rep  can  be  “stolen”  by  a network  eaves- 
dropper, and  as  such  may  enable  unauthorized  access.  In  many  environments  this  level  of  secu- 
rity is  not  a concern,  but  if  it  is,  you  need  to  know  the  exact  semantics  of  the  particular  magic 
cookie  to  know  if  this  is  actually  a problem. 
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Geometry  Specifications 

One  of  the  advantages  of  using  window  systems  instead  of  hardwired  terminals  is  that  applica- 
tions don’t  have  to  be  restricted  to  a particular  size  or  location  on  the  screen.  Although  the  lay- 
out of  windows  on  a display  is  controlled  by  the  window  manager  that  the  user  is  running 
(described  below),  most  X programs  accept  a command  line  argument  of  the  form  -geometry 
widthxheight+xoff+yoff  (where  width,  height,  xoff,  and  yoff  are  numbers)  for 
specifying  a preferred  size  and  location  for  this  application’s  main  window. 


The  width  and  height  parts  of  the  geometry  specification  are  usually  measured  in  either 
pixels  or  characters,  depending  on  the  application.  The  xoff  and  yoff  parts  are  measured  in 
pixels  and  are  used  to  specify  the  distance  of  the  window  from  the  left  or  right  and  top  and  bot- 
tom edges  of  the  screen,  respectively.  Both  types  of  offsets  are  measured  from  the  indicated 
edge  of  the  screen  to  the  corresponding  edge  of  the  window.  The  x offset  may  be  specified  in 
the  following  ways: 


-i -xoff  The  left  edge  of  the  window  is  to  be  placed  xoff  pixels  in  from  the  left  edge 

of  the  screen  (i.e.,  the  x coordinate  of  the  window’s  origin  will  be  xoff). 
xoff  may  be  negative,  in  which  case  the  window’s  left  edge  will  be  off  the 
screen. 

-xoff  The  right  edge  of  the  window  is  to  be  placed  xoff  pixels  in  from  the  right 

edge  of  the  screen,  xoff  may  be  negative,  in  which  case  the  window’s  right 
edge  will  be  off  the  screen. 


The  y offset  has  similar  meanings: 


+yoff 


-yoff 


The  top  edge  of  the  window  is  to  be  yoff  pixels  below  the  top  edge  of  the 
screen  (i.e.,  the  y coordinate  of  the  window’s  origin  will  be  yoff).  yoff 
may  be  negative,  in  which  case  the  window’s  top  edge  will  be  off  the  screen. 

The  bottom  edge  of  the  window  is  to  be  yoff  pixels  above  the  bottom  edge 
of  the  screen,  yoff  may  be  negative,  in  which  case  the  window’s  bottom 
edge  will  be  off  the  screen. 


Offsets  must  be  given  as  pairs:  in  other  words,  in  order  to  specify  either  xoff  or  yoff  both 
must  be  present.  Windows  can  be  placed  in  the  four  comers  of  the  screen  using  the  following 
specifications: 


+0+0 


The  upper  left  hand  comer. 


-0  + 0 


The  upper  right  hand  comer. 


-0-0 


The  lower  right  hand  comer. 


+0-0  The  lower  left  hand  comer. 

In  the  following  examples,  a terminal  emulator  will  be  placed  in  roughly  the  center  of  the 
screen  and  a load  average  monitor,  mailbox,  and  clock  will  be  placed  in  the  upper  right  hand 

comer 
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% xtarm  -fn  6x10  -gaomntry  80x24+30+200  & 

% xclock  - geomat ry  48x48-0+0  & 

% xload  -geometry  48x48-96+0  £ 

% xbiff  -geometry  48x48-48+0  £ 

Window  Managers 

The  layout  of  windows  on  the  screen  is  controlled  by  special  programs  called  window  manag- 
ers. Although  many  window  managers  will  honor  geometry  specifications  as  given,  others  may 
choose  to  ignore  them  (requiring  the  user  to  explicitly  draw  the  window’s  region  on  the  screen 
with  the  pointer,  for  example). 

Since  window  managers  are  regular  (albeit  complex)  client  programs,  a variety  of  different  user 
interfaces  can  be  built.  In  Release  4,  the  core  distribution  comes  with  a window  manager 
named  twm,  which  supports  overlapping  windows,  popup  menus,  point-and-click  or 
click-to-type  input  models,  titlebars,  nice  icons  (and  an  icon  manager  for  those  who  don’t  like 
separate  icon  windows). 

Several  other  window  managers  are  available  in  the  Release  4 user-contributed  distribution: 
uwm,  gwm,  mswm,  olwm,  and  tekwm . 

Font  Names 

Collections  of  characters  for  displaying  text  and  symbols  in  X are  known  as  fonts.  A font  typi- 
cally contains  images  that  share  a common  appearance  and  look  nice  together  (for  example,  a 
single  size,  boldness,  slant,  and  character  set).  Similarly,  collections  of  fonts  that  are  based  on 
a common  type  face  (the  variations  are  usually  called  roman,  bold,  italic,  bold  italic,  oblique, 
and  bold  oblique)  are  called  families. 

Sets  of  font  families  of  the  same  resolution  (usually  measured  in  dots  per  inch)  are  further 
grouped  into  directories  (so  named  because  they  were  initially  stored  in  file  system  directories). 
Each  directory  contains  a database  that  lists  the  name  of  the  font  and  information  on  how  to 
find  the  font.  The  server  uses  these  databases  to  translate  font  names  (which  have  nothing  to  do 
with  filenames)  into  font  data. 

The  list  of  font  directories  in  which  the  server  looks  when  trying  to  find  a font  is  controlled  by 
the  font  path.  Although  most  installations  will  choose  to  have  the  server  start  up  with  all  of  the 
commonly  used  font  directories,  the  font  path  can  be  changed  at  any  time  with  the  xset  pro- 
gram. However,  it  is  important  to  remember  that  the  directory  names  are  on  the  server’s 
machine,  not  on  the  application’s. 

The  default  font  path  for  the  sample  server  contains  three  directories: 

/usrllib/Xl  1 1 fonts!  misc 

This  directory  contains  several  miscellaneous  fonts  that  are  useful  on  all  sys- 
tems. It  contains  a small  family  of  fixed-width  fonts  in  pixel  heights  5 
through  10,  a family  of  fixed-width  fonts  from  Dale  Schumacher  in  similar 
pixel  heights,  several  Kana  fonts  from  Sony  Corporation,  a Kanji  font,  the 
standard  cursor  font,  two  cursor  fonts  from  Digital  Equipment  Corporation, 
and  OPEN  LOOK  cursor  and  glyph  fonts  from  Sun  Microsystems.  It  also  has 
font  name  aliases  for  the  fonts  fixed  and  variable. 
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/usr/lib/Xl  1 1 fonts/75  dpi 

This  directory  contains  fonts  contributed  by  Adobe  Systems,  Inc.,  Digital 
Equipment  Corporation,  Bitstream,  Inc.,  Bigelow  and  Holmes,  and  Sun 
Microsystems,  Inc.  for  75  dots  per  inch  displays.  An  integrated  selection  of 
sizes,  styles,  and  weights  is  provided  for  each  family. 

/ usr/lib/Xl  1 / fonts/ 1 00dpi 

This  directory  contains  100  dots  per  inch  versions  of  the  fonts  in  the  75dpi 
directory. 

Font  databases  are  created  by  running  the  mkfontdir  program  in  the  directory  containing  the 
source  or  compiled  versions  of  the  fonts  (in  both  compressed  and  uncompressed  formats). 
Whenever  fonts  are  added  to  a directory,  mkfontdir  should  be  rerun  so  that  the  server  can  find 
the  new  fonts.  To  make  the  server  reread  the  font  database,  reset  the  font  path  with  the  xset 
program.  For  example,  to  add  a font  to  a private  directory,  the  following  commands  could  be 
used: 

% cp  nowfont.anf  ~ /my font a 
% mkfontdir  “/myfonts 
% xsat  fp  rehash 

The  xlsfonts  program  can  be  used  to  list  all  of  the  fonts  that  are  found  in  font  databases  in  the 
current  font  path.  Font  names  tend  to  be  fairly  long  as  they  contain  all  of  the  information 
needed  to  uniquely  identify  individual  fonts.  However,  the  sample  server  supports  wildcarding 
of  font  names,  so  the  full  specification: 

-adobe -courier-medium-r-normal — 10-100-75-75-m-60-iso8859-l 

could  be  abbreviated  as: 

* -courier-medium-r-normal — *-100-* 

Because  the  shell  also  has  special  meanings  for  * and  ?,  wildcarded  font  names  should  be 
quoted: 

% xlsfonts  -fn  ' *-courier-med±um-r-normal--*-100-* ' 

If  more  than  one  font  in  a given  directory  in  the  font  path  matches  a wildcarded  font  name,  the 
choice  of  which  particular  font  to  return  is  left  to  the  server.  However,  if  fonts  from  more  than 
one  directory  match  a name,  the  returned  font  will  always  be  from  the  first  such  directory  in  the 
font  path.  The  example  given  above  will  match  fonts  in  both  the  75dpi  and  100dpi  directories; 
if  the  75dpi  directory  is  ahead  of  the  100dpi  directory  in  the  font  path,  the  smaller  version  of 
the  font  will  be  used. 

Color  Names 

Most  applications  provide  ways  of  tailoring  (usually  through  resources  or  command  line  argu- 
ments) the  colors  of  various  elements  in  the  text  and  graphics  they  display.  Although  black  and 
white  displays  don’t  provide  much  of  a choice,  color  displays  frequently  allow  anywhere 
between  16  and  16  million  different  colors. 
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Colors  are  usually  specified  by  their  commonly-used  names  (for  example,  red,  white,  or 
medium  slate  blue).  The  server  translates  these  names  into  appropriate  screen  colors  using  a 
color  database  that  can  usually  be  found  in  lusrlliblXlllrgb.txt.  Color  names  are  case-insensi- 
tive, meaning  that  red.  Red,  and  RED  all  refer  to  the  same  color. 

Many  applications  also  accept  color  specifications  of  the  following  form: 

#rgb 

trrggbb 

trrrgggbbb 

#rrrrggggbbbb 

where  r,  g,  and  b are  hexidecimal  numbers  indicating  how  much  red,  green,  and  blue  should  be 
displayed  (zero  being  none  and  ffff  being  on  full).  Each  field  in  the  specification  must  have  the 
same  number  of  digits  (e.g.,  #rrgb  or  #gbb  are  not  allowed).  Fields  that  have  fewer  than  four 
digits  (e.g.,  #rgb)  are  padded  out  with  zero’s  following  each  digit  (e.g.,  #r000g000b000).  The 
eight  primary  colors  can  be  represented  as: 


black 

#000000000000  (no  color  at  all) 

red 

#ffff00000000 

green 

#0000ffff0000 

blue 

#00000000ffff 

yellow 

#ffffffff0000  (full  red  and  green,  no  blue) 

magenta 

#ffff0000ffff 

cyan 

#0000ffffffff 

white 

#ffffffffffff  (full  red,  green,  and  blue) 

Unfortunately,  RGB  color  specifications  are  highly  unportable  since  different  monitors  produce 
different  shades  when  given  the  same  inputs.  Similarly,  color  names  aren’t  portable  because 
there  is  no  standard  naming  scheme  and  because  the  color  database  needs  to  be  tuned  for  each 
monitor.  Application  developers  should  take  care  to  make  their  colors  tailorable. 

Keys 

The  X keyboard  model  is  broken  into  two  layers:  server-specific  codes  (called  keycodes)  which 
represent  the  physical  keys,  and  server-independent  symbols  (called  keysyms ) which  represent 
the  letters  or  words  that  appear  on  the  keys.  Two  tables  are  kept  in  the  server  for  converting 
keycodes  to  keysyms: 

modifier  list  Some  keys  (such  as  Shift,  Control,  and  Caps  Lock)  are  known  as  modifier  and 
are  used  to  select  different  symbols  that  are  attached  to  a single  key  (such  as 
Shift-a  generates  a capital  A,  and  Control-L  generates  a formfeed  character 
~L).  The  server  keeps  a list  of  keycodes  corresponding  to  the  various  modifier 
keys.  Whenever  a key  is  pressed  or  released,  the  server  generates  an  event 
that  contains  the  keycode  of  the  indicated  key  as  well  as  a mask  that  specifies 
which  of  the  modifer  keys  are  currently  pressed.  Most  servers  set  up  this  list 
to  initially  contain  the  various  shift,  control,  and  shift  lock  keys  on  the  key- 
board. 
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keymap  table  Applications  translate  event  keycodes  and  modifier  masks  into  keysyms  using 
a keysym  table  which  contains  one  row  for  each  keycode  and  one  column  for 
each  of  the  modifiers.  This  table  is  initialized  by  the  server  to  correspond  to 
normal  typewriter  conventions,  but  is  only  used  by  client  programs. 

Although  most  programs  deal  with  keysyms  directly  (such  as  those  written  with  the  X Toolkit 

Intrinsics),  most  programming  libraries  provide  routines  for  converting  keysyms  into  the  appro- 
priate type  of  string  (such  as  ISO  Latin-1). 

Options 

Most  X programs  attempt  to  use  the  same  names  for  command  line  options  and  arguments.  All 

applications  written  with  the  X Toolkit  Intrinsics  automatically  accept  the  following  options: 

-display  [host]  : server[ . screen] 

Specifies  the  name  of  the  X server  to  use.  host  specifies  the  machine, 
server  specifies  the  display  server  number,  and  screen  specifies  the 
screen  number.  Either  or  both  the  host  and  screen  elements  to  the  display 
specification  can  be  omitted.  If  host  is  omitted,  the  local  machine  is 
assumed.  If  screen  is  omitted,  screen  0 is  assumed  (and  the  period  is 
unnecessary).  The  colon  and  (display)  server  are  necessary  in  all  cases. 

-geometry  geometry 

Specifies  the  initial  size  and  location  of  the  application  window.  The 
-geometry  option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a 
conflicting  option  that  begins  with  “g.”  The  argument  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
hei  gh  t±xoff±yoff. 

-bg  color,  -background  color 

Either  option  specifies  the  color  to  use  for  the  window  background. 

-bd  color,  -bordercolor  color 

Either  option  specifies  the  color  to  use  for  the  window  border. 

-bw pixels,  -borderwidth  pixels 

Either  option  specifies  the  width  in  pixels  of  the  window  border. 

-fg  color,  -foreground  color 

Either  option  specifies  the  color  to  use  for  text  or  graphics. 

-fn  font,  -font  font 

Either  option  specifies  the  font  to  use  for  displaying  text. 

-iconic  Indicates  that  the  user  would  prefer  that  the  application’s  windows  initially 

not  be  visible  as  if  the  windows  had  been  immediately  iconified  by  the  user. 
Window  managers  may  choose  not  to  honor  the  application  s request. 

-name  Specifies  the  name  under  which  resources  for  the  application  should  be 

found.  This  option  is  useful  in  shell  aliases  to  distinguish  between  invoca- 
tions of  an  application,  without  resorting  to  creating  links  to  alter  the  execut- 
able filename. 
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-rv,  -reverse 

Either  option  indicates  that  the  program  should  simulate  reverse  video  if  pos- 
sible, often  by  swapping  the  foreground  and  background  colors.  Not  all  pro- 
grams honor  this  or  implement  it  correctly.  It  is  usually  only  used  on  mono- 
chrome displays. 

+rv  Indicates  that  the  program  should  not  simulate  reverse  video.  This  is  used  to 

override  any  defaults  since  reverse  video  doesn’t  always  work  properly. 

- select ionTimeout 

Specifies  the  timeout  in  milliseconds  within  which  two  communicating  appli- 
cations must  respond  to  one  another  for  a selection  request 

-synchronous 

Indicates  that  requests  to  the  X server  should  be  sent  synchronously,  instead 
of  asynchronously.  Since  Xlib  normally  buffers  requests  to  the  server,  errors 
do  not  necessarily  get  reported  immediately  after  they  occur.  This  option 
turns  off  the  buffering  so  that  the  application  can  be  debugged.  It  should 
never  be  used  with  a working  program. 

-title  string 

Specifies  the  title  to  be  used  for  this  window.  This  information  is  sometimes 
used  by  a window  manager  to  provide  some  sort  of  header  identifying  the 
window. 

-xnllanguage  language[_territory][.  codeset] 

Specifies  the  language,  territory,  and  codeset  for  use  in  resolving  resource  and 
other  filenames. 

-xrm  resourcestring 

Specifies  a resource  name  and  value  to  override  any  defaults.  It  is  very  useful 
for  setting  resources  that  don’t  have  explicit  command  line  arguments. 


Resources 

To  make  the  tailoring  of  applications  to  personal  preferences  easier,  X supports  several  mecha- 
nisms for  storing  default  values  for  program  resources  (e.g.,  background  color,  window  title, 
etc.)  Resources  are  specified  as  strings  of  the  form: 

appname*  subname*  subsubname  . . . : value 


that  are  read  in  from  various  places  when  an  application  is  run. 

By  convention,  the  application  class  name  is  the  same  as  the  program  name,  but  with  the  first 
letter  capitalized  (e.g..  Bitmap  or  Emacs ) although  some  programs  that  begin  with  the  letter 
“x”  also  capitalize  the  second  letter  for  historical  reasons.  The  precise  syntax  for  resources  is: 


ResourceLine 

Comment 

ResourceSpec 

ResourceName 

Binding 

WhiteSpace 


Comment  | ResourceSpec 
" ! " string  I <empty  line> 

WhiteSpace  ResourceName  WhiteSpace  WhiteSpace  value 

[Binding]  ComponentName  {Binding  ComponentName } 

ft  «f  | II  * It 

{"  " I "\t"} 
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ComponentName  = 
value  = 
string 


{ 3 z | "A"-"Z"  | " 0"  — " 9"  | " " | ■> _ ii  j 
string 

{ <any  character  not  including  "\n">} 


Note  that  elements  enclosed  in  curly  braces  ({...})  indicate 
enclosed  elements. 


zero  or  more  occurrences  of  the 


To  allow  values  to  contain  arbitrary  octets,  the  4-character  sequence  W,  where  n is  a digit  in 
die  range  of  0 - 7 is  recognized  and  replaced  with  a single  byte  that  contains  this  sequence 
interpreted  asan  octal  number.  For  example,  a value  containing  a NULL  byte  can  be  stored  by 
specifying  NOOO  . 3 


The  Xlib  routine  XGetDefault( 3X)  and  the  resource  utilities  within  the  X Toolkit  obtain 
resources  from  the  following  sources: 

RESOURCE_MANAGER  root  window  property 

Any  global  resources  that  should  be  available  to  clients  on  all  machines 
should  be  stored  in  the  RESOURCE.MANAGER  property  on  the  root  window 
using  the  xrdb  program.  This  is  frequently  taken  care  of  when  the  user  starts 
up  X through  the  display  manager  or  xinit. 

application-specific  files 

Any  application-  or  machine-specific  resources  can  be  stored  in  the  class 
resource  files  located  in  the  XAPPLOADDIR  directory  (this  is  a configuration 
parameter  that  is  /usr/lib/Xl  1 /app-defaults  in  the  standard  distribution).  Pro- 
grams that  use  the  X Toolkit  will  also  look  in  the  directory  named  by  the 
environment  variable  XAPPLRESDIR  (default  value  is  user’s  home  directory) 
for  files  named  Class  where  Class  is  the  class  name  of  the  particular  applica- 
tion. XAPPLOADDIR  and  XAPPLRESDIR  configuration  files  are  actually 
loaded  before  the  RESOURCE_MANAGER  property,  so  that  the  property  can 
override  the  values. 


XENVIRONMENT 

Any  user-  and  machine-specific  resources  may  be  specified  by  setting  the 
XENVIRONMENT  environment  variable  to  the  name  of  a resource  file  to  be 
loaded  by  all  applications.  If  this  variable  is  not  defined,  the  X Toolkit  looks 
for  a file  named  Xdefaults-hostname , where  hostname  is  the  name  of  the  host 
where  the  application  is  executing. 

-xrm  resourcestring 

Applications  that  use  the  X Toolkit  can  have  resources  specified  from  the 
command  line.  The  resourcestring  is  a single  resource  name  and  value 
as  shown  above.  Note  that  if  the  string  contains  characters  interpreted  by  the 
shell  (e.g.,  asterisk),  they  must  be  quoted.  Any  number  of  -xrm  arguments 
may  be  given  on  the  command  line. 

Program  resources  are  organized  into  groups  called  classes,  so  that  collections  of  individual 
resources  (each  of  which  are  called  instances ) can  be  set  all  at  once.  By  convention,  the 
instance  name  of  a resource  begins  with  a lowercase  letter  and  class  name  with  an  upper  case 
letter.  Multiple  word  resources  are  concatentated  with  the  first  letter  of  the  succeeding  words 
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capitalized.  Applications  written  with  the  X Toolkit  Intrinsics  will  have  at  least  the  following 
resources: 

background  (class  Background) 

Specifies  the  color  to  use  for  the  window  background. 

borderWidth  (class  BorderWidth) 

Specifies  the  width  in  pixels  of  the  window  border. 

borderColor  (class  BorderColor) 

Specifies  the  color  to  use  for  the  window  border. 

Most  applications  using  the  X Toolkit  Intrinsics  also  have  the  resource  foreground  (class 
Foreground),  specifying  the  color  to  use  for  text  and  graphics  within  the  window. 

By  combining  class  and  instance  specifications,  application  preferences  can  be  set  quickly  and 
easily.  Users  of  color  displays  will  frequently  want  to  set  Background  and  Foreground 
classes  to  particular  defaults.  Specific  color  instances  such  as  text  cursors  can  then  be  overrid- 
den without  having  to  define  all  of  the  related  resources.  For  example, 

bitmap*Dashed : off 

XTerm*cursorColor : gold 

XTerm*mult iScroll : on 
XTerm* jumpScroll : on 
XTerm*reverseWrap : on 

XTerm*curses:  on 

XTerm*Font:  6x10 

XTerm*scrollBar : on 
XTerm*scrollbar *thickness : 5 
XTerm*multiClickTime : 500 

XTerm* char Class : 33:48,37:48,45-47:48,64:48 

XTerm*cutNewline : off 
XTerm*cutToBeginningOfLine : off 
XTerm*titeInhibit : on 

XTerm*ttyModes : intr  “c  erase  “?  kill  ~u 

XLoad*Background : gold 

XLoad*Foreground : red 

XLoad*highlight : black 

XLoad*borderWidth : 0 

emacs*Geometry : 80x65-0-0 

emacs*Background : #5b7686 

emacs*Foreground : white 

emacs*Cursor : white 

emacs*BorderColor : white 

emacs*Font:  6x10 

xmag*geometry : -0-0 

xmag*borderColor : white 
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If  these  resources  were  stored  in  a file  called  J (resources  in  your  home  directory,  they  could  be 
added  to  any  existing  resources  in  the  server  with  the  following  command: 

% xrdb  -marge  $HOME/ . Xresources 

This  is  frequently  how  user-friendly  startup  scripts  merge  user-specific  defaults  into  any  site- 
wide defaults.  All  sites  are  encouraged  to  set  up  convenient  ways  of  automatically  loading 
resources. 

Examples 

The  following  is  a collection  of  sample  command  lines  for  some  of  the  more  frequently  used 
commands.  For  more  information  on  a particular  command,  please  refer  to  that  command’s 
manual  page. 

% xrdb  -load  $HOME/. Xresources 
% xmodmap  -a  'kaysym  Backspace  = Delete' 

% mkfontdir  /usr/local/lib/Xll/otherfonta 
% xset  fp+  /usr/local/lib/Xll/otherfonta 
% xmodmap  $HOME/.keymap.km 
% xsatroot  -solid  '#888' 

% xset  b 100  400  c 50  s 1800  r on 
% xset  q 
% twm 
% xmag 

% xclock  -geometry  48x48-0+0  -bg  blue  -fg  white 
% xeyes  -geometry  48x48-48+0 
% xbiff  -update  20 
% xlsfonts  ' *helvetica* ' 

% xlswins  -1 
% xwininfo  -root 

% xdpyinfo  -display  joesworkstation : 0 
% xhost  -joesworkstation 
% xrefresh 
% xwd  | xwud 

% bitmap  companylogo . bm  32x32 

% xcalc  -bg  blue  -fg  magenta 

% xterm  -geometry  80x66-0-0  -name  myxterm 

Diagnostics 

A wide  variety  of  error  messages  are  generated  from  various  programs.  Various  toolkits  are 
encouraged  to  provide  a common  mechanism  for  locating  error  text  so  that  applications  can  be 
tailored  easily.  Programs  written  to  interface  directly  to  the  Xlib  C language  library  are 
expected  to  do  their  own  error  checking. 

The  default  error  handler  in  Xlib  (also  used  by  many  toolkits)  uses  standard  resources  to  con- 
struct diagnostic  messages  when  errors  occur.  The  defaults  for  these  messages  are  usually 
stored  in  lusr/lib/Xl  1 IXErrorDB . If  this  file  is  not  present,  error  messages  will  be  rather  terse 
and  cryptic. 
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When  the  X Toolkit  Intrinsics  encounter  errors  converting  resource  strings  to  the  appropriate 
internal  format,  no  error  messages  are  printed.  This  is  convenient  when  it  is  desirable  to  have 
one  set  of  resources  across  a variety  of  displays  (e.g.,  color  versus  monochrome,  lots  of  fonts 
versus  very  few,  etc.),  although  it  can  pose  problems  for  trying  to  determine  why  an  application 
might  be  failing.  This  behavior  can  be  overridden  by  setting  the  StringConversions- 
Warning  resource. 

To  force  the  X Toolkit  Intrinsics  to  always  print  string  conversion  error  messages,  the  following 
resource  should  be  placed  at  the  top  of  the  file  that  gets  loaded  onto  the  RESOURCE_MANAGER 
property  using  the  xrdb  program  (frequently  called  X resources  or  Xres  in  the  user’s  home 
directory): 

*StringConversionWarnings : on 

To  have  conversion  messages  printed  for  just  a particular  application,  the  appropriate  instance 
name  can  be  placed  before  the  asterisk: 

xterm*StringConversionWarnings : on 


Bugs 

If  you  encounter  a repeatable  bug,  please  contact  your  site  administrator  for  instructions  on 
how  to  submit  an  X Bug  Report. 

See  Also 

XConsortium(l),  XStandards(l),  Xau,  Xserver,  mkfontdir,  bdftosnf,  bitmap,  bsdtosnf,  oclock, 
showsnf,  twm,  uwm,  xlOtoxll,  xauth,  xbiff,  xcalc,  xclock,  xdpyinfo,  xedit,  xev,  xfd,  xfontsel, 
xhost,  xinit,  xkill,  xload,  xlogo,  xlsclients,  xlsfonts,  xlswins,  xmag,  xman,  xmh,  xmodmap,  xpr, 
xprop,  xrdb,  xrefresh,  xset,  xsetroot,  resize,  xterm,  xwd,  xwininfo,  xwud,  biff(l),  mh(l),  init(8), 
ttys(5);  Volume  One,  Xlib  Programming  Manual ; Volume  Two,  Xlib  Reference  Manual ; Vol- 
ume Four,  X Toolkit  Intrinsics  Programming  Manual ; Volume  Five,  X Toolkit  Intrinsics  Refer- 
ence Manual. 

Copyright 

The  following  copyright  and  permission  notice  outlines  the  rights  and  restrictions  covering 
most  parts  of  the  standard  distribution  of  the  X Window  System  from  MIT.  Other  parts  have 
additional  or  different  copyrights  and  permissions;  see  the  individual  source  files. 

Copyright  1984,  1985, 1986, 1987, 1988, 1989  Massachusetts  Institute  of  Technology. 

Permission  to  use,  copy,  modify,  and  distribute  this  software  and  its  documentation  for  any  pur- 
pose and  without  fee  is  hereby  granted,  provided  that  the  above  copyright  notice  appear  in  all 
copies  and  that  both  that  copyright  notice  and  this  permission  notice  appear  in  supporting  docu- 
mentation, and  that  the  name  of  M.I.T.  not  be  used  in  advertising  or  publicity  pertaining  to  dis- 
tribution of  the  software  without  specific,  written  prior  permission.  M.I.T.  makes  no  represen- 
tations about  the  suitability  of  this  software  for  any  purpose.  It  is  provided  “as  is”  without 
express  or  implied  warranty. 
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This  software  is  not  subject  to  any  license  of  the  American  Telephone  and  Telegraph  Company 
or  of  the  Regents  of  the  University  of  California. 

Trademarks 

UNIX  and  OPEN  LOOK  are  trademarks  of  AT&T.  X Window  System  is  a trademark  of  MIT. 

Authors 

A cast  of  thousands.  See  the  file  doc! contributors  in  the  standard  sources  for  some  of  the 
names. 
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Name 

XauFileName,  XauReadAuth,  XauLockAuth, 

XauUnlockAuth,  XauWriteAuth,  XauGetAuthByAddr  - X authority  database  routines 

Syntax 

tinclude  <X11/Xauth.h> 
typedef  struct  xauth  { 


unsigned 

short 

family; 

unsigned 

short 

address  length 

char 

♦address; 

unsigned 

short 

number  length; 

char 

♦number; 

unsigned 

short 

name  length; 

char 

♦name; 

unsigned 

short 

data  length; 

char 

♦data; 

} Xauth; 

char  *XauFileName  () 

Xauth  *XauReadAuth  (auth_file) 

FILE  *auth_file; 

int  XauWriteAuth  ( auth_file , auth) 

FILE  *auth_file; 

Xauth  *auth; 

Xauth  ♦XauGetAuthByAddr  ( family , address_length,  address , 
number_length,  number ) 
unsigned  short  family; 
unsigned  short  address_length; 
char  *address; 

unsigned  short  number_length; 
char  * number; 

int  XauLockAuth  (filename,  retries,  timeout,  dead) 
char  *file_name; 
int  retries; 
int  timeout; 
long  dead; 

int  XauUnlockAuth  ( file_name ) 
char  *file_name; 

XauDisposeAuth  {auth) 

Xauth  *auth; 


Description 

XauFileName  generates  the  default  authorization  file  name  by  first  checking  the  XAU- 
THORITY  environment  variable  if  set,  else  it  returns  $HOME/ Xauthority . This  name  is  stati- 
cally allocated  and  should  not  be  freed. 
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XauReadAuth  reads  the  next  entry  from  auth_file.  The  entry  is  not  statically  allocated 
and  should  be  freed  by  calling  XauDisposeAuth. 

XauWriteAuth  writes  an  authorization  entry  to  auth__file.  It  returns  1 on  success,  0 on 
failure. 


XauGetAuthByAddr  searches  for  an  entry  which  matches  the  given  network  address/display 
number  pair.  The  entry  is  not  statically  allocated  and  should  be  freed  by  calling  Xau- 
DisposeAuth 


XauLockAuth  does  the  work  necessary  to  synchronously  update  an  authorization  file.  First  it 
makes  to  file  names,  one  with  -c  appended  to  file_name,  the  other  with  -1  appended.  If 
the  -c  file  already  exists  and  is  more  than  dead  seconds  old,  XauLockAuth  removes  it  and 
the  associated  -1  file.  To  prevent  possible  synchronization  troubles  with  NFS,  a dead  value  of 
zero  forces  the  files  to  be  removed.  XauLockAuth  makes  retries  attempts  to  create  and  link 
the  file  names,  pausing  timeout  seconds  between  each  attempt.  XauLockAuth  returns  a 
collection  of  values  depending  on  the  results: 


LOCK_ERROR  A system  error  occurred,  either  a file_name  which  is  too  long,  or  an 
unexpected  failure  from  a system  call,  errno  may  prove  useful. 

LOCK_T IMEOUT  retries  attempts  failed. 

LOCK_SUCCESS  The  lock  succeeded. 

XauUnlockAuth  undoes  the  work  of  XauLockAuth  by  unlinking  both  the  -c  and  -1 
filenames. 

XauDisposeAuth  frees  storage  allocated  to  hold  an  authorization  entry. 

See  Also 

xauth,  xdm 


Author 

Keith  Packard,  MIT  X Consortium. 
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Name 

X - X Window  System  server. 

Syntax 

X [:  display  number]  [options]  [ttyname] 

Description 

X is  the  generic  name  for  the  X Window  System  server.  It  is  frequently  a link  or  a copy  of  the 
appropriate  server  binary  for  driving  the  most  frequently  used  server  on  a given  machine.  The 
sample  server  from  MIT  supports  the  following  platforms: 


Xqvss 
Xqdss 
Xsun 
Xhp 
Xibm 
Xapollo 
XmacII 
Xcfbpmax 
Xmfbpmax 
Xtek 

Starting  the  Server 

The  server  is  usually  started  from  the  X Display  Manager  program,  xdm.  This  utility  is  run 
from  the  system  boot  files  and  takes  care  of  keeping  the  server  running,  prompting  for  user- 
names  and  passwords,  and  starting  up  the  user  sessions.  It  is  easily  configured  for  sites  that 
wish  to  provide  nice,  consistent  interfaces  for  novice  users  (loading  convenient  sets  of 
resources,  starting  up  a window  manager,  clock,  and  nice  selection  of  terminal  emulator  win- 
dows). 

Since  xdm  now  handles  automatic  starting  of  the  server  in  a portable  way,  the  -L  option  to 
xterm  is  now  considered  obsolete.  Support  for  starting  a login  window  from  BSD  4.3-derived 
I etc! ttys  files  is  no  longer  included  as  of  Release  4. 

Installations  that  run  more  than  one  window  system  will  still  need  to  use  the  xinit  utility.  How- 
ever, xinit  is  to  be  considered  a tool  for  building  startup  scripts  and  is  not  intended  for  use  by 
end  users.  Site  adminstrators  are  strongly  urged  to  build  nicer  interfaces  for  novice  users. 

When  the  sample  server  starts  up,  it  takes  over  the  display.  If  you  are  running  on  a workstation 
whose  console  is  the  display,  you  cannot  log  into  the  console  while  the  server  is  running. 

Network  Connections 

The  sample  server  supports  connections  made  using  the  following  reliable  byte-streams: 

TCP/IP  The  server  listens  on  port  htons(6000+/i),  where  n is  the  display  number. 

UNIX  Domain  The  sample  server  uses  Itmp/Xll-unix/Xn  as  the  filename  for  the  socket, 
where  n is  the  display  number. 


Digital  monochrome  vaxstationll  or  II 
Digital  color  vaxstationll  or  II 
Sun  monochrome  or  color  Sun  2, 3,  or  4 
HP  Topcat  9000s  300 

IBM  AED,  APA  and  megapel  PC/RT,  8514  and  VGA  PS/2  model  80 
Apollo  monochrome  or  color  (Domain/OS  SR  10.1  or  SR  10.2) 

Apple  monochrome  Macintosh  II 
Digital  color  DECstation  3100 
Digital  monochrome  DECstation  3100 
Tektronix  4319  (this  is  the  only  tested  configuration) 
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DECnet  The  server  responds  to  connections  to  object  X$Xn,  where  n is  the  display 

number. 

Options 

All  of  the  sample  servers  accept  the  following  command  line  options: 

-a  number  Sets  pointer  acceleration  (i.e.,  the  ratio  of  how  much  is  reported  to  how  much 
the  user  actually  moved  the  pointer). 

-auth  authorization-file 

Specifies  a file  which  contains  a collection  of  authorization  records  used  to 
authenticate  access.  (Available  as  of  Release  4.) 

be  Disables  certain  kinds  of  error  checking,  for  bug  compatibility  with  previous 

releases  (e.g.,  to  work  around  bugs  in  Release  2 and  Release  3 versions  of 
xterm  and  the  toolkits).  Use  of  this  option  is  discouraged.  (Available  as  of 
Release  4.) 

-bs  Disables  backing  store  support  on  all  screens. 

-c  Turns  off  key-click. 

c vol  ume  Sets  key-click  volume  (allowable  range:  0-8). 

-cc  class  Sets  the  visual  class  for  the  root  window  of  color  screens.  The  class  numbers 
are  as  specified  in  the  X protocol.  Not  obeyed  by  all  servers.  (Available  as  of 
Release  4.) 

-dpi  resolution 

Sets  the  resolution  of  the  screen,  in  dots  per  inch.  To  be  used  when  the  server 
cannot  determine  the  screen  size  from  the  hardware.  (Available  as  of  Release 
4.) 

-f  volume  Sets  beep  (bell)  volume  (allowable  range:  0-7). 

-I  Causes  all  remaining  command  line  arguments  to  be  ignored.  (Available  as 

of  Release  4.) 

-Id  kilobytes 

Sets  the  data  space  limit  of  the  server  to  the  specified  number  of  kilobytes. 
The  default  value  is  zero,  making  the  data  size  as  large  as  possible.  A value 
of  -1  leaves  the  data  space  limit  unchanged.  (Available  as  of  Release  4;  not 
available  in  all  operating  systems.) 

-Is  kilobytes 

Sets  the  stack  space  limit  of  the  server  to  the  specified  number  of  kilobytes. 
The  default  value  is  zero,  making  the  stack  size  as  large  as  possible.  A value 
of  -1  leaves  the  stack  space  limit  unchanged.  This  option  is  not  available  in 
all  operating  systems.  (Available  as  of  Release  4;  not  available  in  all  operat- 
ing systems.) 

-logo  Turns  on  the  X Window  System  logo  display  in  the  screen-saver.  There  is 

currently  no  way  to  change  this  from  a client. 
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nologo 

-p  minutes 

-r 

r 

-s  minutes 
-su 

-t  numbers 

-to  seconds 

v 

-v 


Turns  off  the  X Window  System  logo  display  in  the  screen-saver.  There  is 
currently  no  way  to  change  this  from  a client. 

Sets  screen-saver  pattern  cycle  time  in  minutes. 

Turns  off  auto-repeat. 

Turns  on  auto-repeat. 

Sets  screen-saver  timeout  in  minutes. 

Disables  save  under  support  on  all  screens. 

Sets  pointer  acceleration  threshold  in  pixels  (i.e.,  after  how  many  pixels 
pointer  acceleration  should  take  effect). 

Sets  default  screen-saver  timeout  in  seconds. 

Sets  video-on  screen-saver  preference. 

Sets  video-off  screen-saver  preference. 


-co  filename 

Sets  the  name  of  the  RGB  color  database. 


-help  Prints  a usage  message. 

-fp  fontPath 

Sets  the  search  path  for  fonts.  This  path  is  a comma-separated  list  of  direc- 
tories the  server  searches  for  font  databases. 

-fc  cursorFont 

Sets  the  default  cursor  font 

-fn  font  Sets  the  default  font. 

-wm  Forces  the  default  backing-store  of  all  windows  to  be  WhenMapped;  a cheap 

trick  way  of  getting  backing-store  to  apply  to  all  windows. 

-x  extension  Loads  the  specified  extension  at  init.  (Available  as  of  Release  4;  not  sup- 
ported in  most  implementations.) 

XDMCP-specific  Options  (Release  4) 

You  can  also  have  the  X server  connect  to  xdm  using  XDMCP.  Although  this  is  not  typically 
useful  as  it  doesn’t  allow  xdm  to  manage  the  server  process,  it  can  be  used  to  debug  XDMCP 
implementations,  and  servers  as  a sample  implementation  of  the  server  side  of  XDMCP.  For 
more  information  on  this  protocol,  see  the  XDMCP  specification  in  docs/XDMCP/xdmcp.ms. 
The  following  options  control  the  behavior  of  XDMCP: 

-query  host-name 

Enables  XDMCP  and  sends  Query  packets  to  the  specified  host. 

-broadcast  Enables  XDMCP  and  broadcasts  BroadcastQuery  packets  to  the  network. 
The  first  responding  display  manager  will  be  chosen  for  the  session. 

-indirect  host-name 

Enables  XDMCP  and  sends  Indirect  Query  packets  to  the  specified  host. 
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-port  port-num 

Specifies  an  alternate  port  number  for  XDMCP  packets.  Must  be  specified 
before  any  -query,  -broadcast  or  -indirect  options. 

-once  Makes  the  server  exit  after  the  first  session  is  over.  Normally,  the  server 

keeps  starting  sessions,  one  after  the  other. 

-class  display-class 

XDMCP  has  an  additional  display  qualifier  used  in  resource  lookup  for  dis- 
play-specific options.  This  option  sets  that  value;  by  default  it  is  "MIT- 
Unspecified"  (not  a very  useful  value). 

-cookie  xdm-auth-bits 

When  testing  XDM- AUTHENTICATION- 1 , a private  key  is  shared  between 
the  server  and  the  manager.  This  option  sets  the  value  of  that  private  data 
(not  that  it’s  very  private,  being  on  the  command  line). 

-displaylD  display-id 

Yet  another  XDMCP-specific  value,  this  one  allows  the  display  manager  to 
identify  each  display  so  that  it  can  locate  the  shared  key. 

Many  servers  also  have  device-specific  command  line  options.  See  the  manual  pages  for  the 
individual  servers  for  more  details. 

Security 

As  of  Release  4,  the  sample  server  implements  a simplistic  authorization  protocol,  MIT- 
MAGIC-COOKIE- 1 , which  uses  data  private  to  authorized  clients  and  the  server.  This  is  a 
rather  trivial  scheme;  if  the  client  passes  authorization  data  which  is  the  same  as  the  server  has, 
it  is  allowed  access.  This  scheme  is  worse  than  the  host-based  access  control  mechanisms  in 
environments  with  unsecure  networks  as  it  allows  any  host  to  connect,  given  that  it  has 
discovered  the  private  key.  But  in  many  environments,  this  level  of  security  is  better  than  the 
host-based  scheme  as  it  allows  access  control  per-user  instead  of  per-host. 

In  addition,  the  server  provides  support  for  a DES-based  authorization  scheme,  XDM- 
AUTHORIZATTON-1,  which  is  more  secure  (given  a secure  key  distribution  mechanism),  but 
as  DES  is  not  generally  distributable,  the  implementation  is  missing  routines  to  encrypt  and 
decrypt  the  authorization  data.  This  authorization  scheme  can  be  used  in  conjunction  with 
XDMCP’s  authentication  scheme,  XDM- AUTHENTICATION- 1 or  in  isolation. 

The  authorization  data  is  passed  to  the  server  in  a private  file  named  with  the  -auth  command 
line  option.  Each  time  the  server  is  about  to  accept  the  first  connection  after  a reset  (or  when 
the  server  is  starting),  it  reads  this  file.  If  this  file  contains  any  authorization  records,  the  local 
host  is  not  automatically  allowed  access  to  the  server,  and  only  clients  which  send  one  of  the 
authorization  records  contained  in  the  file  in  the  connection  setup  information  will  be  allowed 
access.  See  the  Xau  manual  page  for  a description  of  the  binary  format  of  this  file.  Mainte- 
nance of  this  file,  and  distribution  of  its  contents  to  remote  sites  for  use  there,  is  left  as  an  exer- 
cise for  the  reader. 

The  sample  server  also  uses  a host-based  access  control  list  for  deciding  whether  or  not  to 
accept  connections  from  clients  on  a particular  machine.  This  list  initially  consists  of  the  host 
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on  which  the  server  is  running  as  well  as  any  machines  listed  in  the  file  /etc/Xn.hosts,  where  n is 
the  display  number  of  the  server.  Each  line  of  the  file  should  contain  either  an  Internet  host- 
name  (e.g.,  expo.lcs.mit.edu)  or  a DECnet  hostname  in  double  colon  format  (e.g.,  hydra::). 
There  should  be  no  leading  or  trailing  spaces  on  any  lines.  For  example: 

joes works tat ion 
. corporate.company.com 
star : : 
bigcpu : : 

Users  can  add  or  remove  hosts  from  this  list  and  enable  or  disable  access  control  using  the 
xhost  command  from  the  same  machine  as  the  server.  For  example: 

% xhost  + janasworJcstation  janesworkstation  added  to  access  control  list 

% xhost  -star : : star::  removed  from  access  control  list 

% xhost  + all  hosts  allowed  (access  control  disabled) 

% xhost  - all  hosts  restricted  (access  control  enabled) 

% xhost 

access  control  enabled  (only  the  following  hosts  are  allowed) 

joesworkstation 

janesworkstation 

corporate . company . com 

bigcpu : : 

Unlike  some  window  systems,  X does  not  have  any  notion  of  window  operation  permissions  or 
place  any  restrictions  on  what  a client  can  do;  if  a program  can  connect  to  a display,  it  has  full 
run  of  the  screen.  Sites  that  have  authentication  and  authorization  systems  (such  as  Kerberos) 
might  wish  to  make  use  of  the  hooks  in  the  libraries  and  the  server  to  provide  additional  secu- 
rity. 

Signals 

The  sample  server  attaches  special  meaning  to  the  following  signals. 

SIGHUP  Causes  the  server  to  close  all  existing  connections,  free  all  resources,  and 

restore  all  defaults.  It  is  sent  by  the  display  manager  whenever  the  main 
user’s  primary  application  (usually  an  xterm  or  window  manager)  exits  to 
force  the  server  to  clean  up  and  prepare  for  the  next  user. 

SIGTERM  Causes  the  server  to  exit  cleanly. 

SIGUSR1  This  signal  is  used  quite  differently  from  either  of  the  above.  When  the 

server  starts,  it  checks  to  see  if  it  has  inherited  SIGUSR1  as  SIG_IGN  instead 
of  the  usual  SIG_DFL.  In  this  case,  the  server  sends  a SIGUSR1  to  its  parent 
process,  after  it  has  set  up  the  various  connection  schemes,  xdm  uses  this  fea- 
ture to  recognize  when  connecting  to  the  server  is  possible. 

Fonts 

Fonts  are  usually  stored  as  individual  files  in  directories.  The  list  of  directories  in  which  the 
server  looks  when  trying  to  open  a font  is  controlled  by  the  font  path.  Although  most  sites  will 
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choose  to  have  the  server  start  up  with  the  appropriate  font  path  (using  the  -fp  option  men- 
tioned above),  it  can  be  overridden  using  the  xset  program. 

The  default  font  path  for  the  sample  server  contains  three  directories: 

/ usr/lib/Xl  1 /font  si mi  sc 

This  directory  contains  several  miscellaneous  fonts  that  are  useful  on  all  sys- 
tems. It  contains  a small  family  of  fixed-width  fonts  in  pixel  heights  5 
through  10,  a family  of  fixed- width  fonts  from  Dale  Schumacher  in  similar 
pixel  heights,  several  Kana  fonts  from  Sony  Corporation,  a Kanji  font,  the 
standard  cursor  font,  two  cursor  fonts  from  Digital  Equipment  Corporation, 
and  OPEN  LOOK  cursor  and  glyph  fonts  from  Sun  Microsystems.  It  also  has 
font  name  aliases  for  the  fonts  fixed  and  variable. 

/usr/lib/Xl  1 lfonts/75dpi 

This  directory  contains  fonts  contributed  by  Adobe  Systems,  Inc.,  Digital 
Equipment  Corporation,  Bitstream,  Inc.,  Bigelow  and  Holmes,  and  Sun 
Microsystems,  Inc.  for  75  dots  per  inch  displays.  An  integrated  selection  of 
sizes,  styles,  and  weights  is  provided  for  each  family. 

/usr/lib/Xl  1 /fonts!  1 00dpi 

This  directory  contains  versions  of  the  fonts  in  the  75dpi  directory  for  100 
dots  per  inch  displays. 

Font  databases  are  created  by  running  the  mkfontdir  program  in  the  directory  containing  the 
compiled  versions  of  the  fonts  (the  .snf  files).  Whenever  fonts  are  added  to  a directory, 
mkfontdir  should  be  rerun  so  that  the  server  can  find  the  new  fonts.  If  mkfontdir  is  not  run,  the 
server  will  not  be  able  to  find  any  fonts  in  the  directory. 

Diagnostics 

Too  numerous  to  list  them  all.  If  run  from  init(S),  errors  are  logged  in  the  file  /usr/adm/Xnmsgs. 

Files 

/etc/Xn.hosts  Initial  access  control  list. 

/ usr/lib/Xl  1/fontslmisc,  lusrllib/Xl  1 lfonts/75dpi,  /usr/lib/Xl  1 /fonts/ 100dpi 
Font  directories. 

lusrlliblXlllrgb.txt  Color  database. 

/tmp/X  1 1 -unix/X n UNIX  domain  socket. 

/usr/adm/Xnmsgs  Error  log  file. 

See  Also 

X,  Xqdss(l),  Xqvss(l),  Xsun(l),  Xapollo(l),  XmacII(l),  Xau,  mkfontdir,  twm,  uwm,  xauth, 
xdm,  xhost,  xinit,  xset,  xsetroot,  xterm,  ttys(5),  init(8);  X Window  System  Protocol ; Definition 
of  the  Porting  Layer  for  the  X vll  Sample  Server;  Strategies  for  Porting  the  X vll  Sample 
Server;  Godzilla’s  Guide  to  Porting  the  XVII  Sample  Server. 
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Bugs 

The  option  syntax  is  inconsistent  with  itself  and  xset. 

The  acceleration  option  should  take  a numerator  and  a denominator  like  the  protocol. 

If  X dies  before  its  clients,  new  clients  won’t  be  able  to  connect  until  all  existing  connections 
have  their  TCP  TIME_WAIT  timers  expire. 

The  color  database  is  missing  a large  number  of  colors.  However,  there  doesn’t  seem  to  be  a 
better  one  available  that  can  generate  RGB  values  tailorable  to  particular  displays. 

Authors 

The  sample  server  was  originally  written  by  Susan  Angebranndt,  Raymond  Drewry,  Philip 
Karlton,  and  Todd  Newman,  of  Digital  Equipment  Corporation,  with  support  from  a large  cast. 
It  has  since  been  extensively  rewritten  by  Keith  Packard  and  Bob  Scheifler  of  MIT. 
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Name 

appres  - list  application  resource  database. 

Syntax 

appres  [[classname  [ instancename ]]  [-xrm  resource] 

Description 

Available  as  of  Release  4,  the  appres  client  prints  the  resources  seen  by  an  application  of  the 
specified  classname  and  instancename.  It  is  used  to  determine  which  resources  a partic- 
ular program  would  load.  For  example: 

% appres  XTerm 

would  list  the  resources  that  any  x term  program  would  load.  To  also  match  particular  instance 
names,  you  can  enter  both  an  instance  and  class  name,  as  in  the  following: 

% appres  XTerm  myxterm 

If  no  application  class  is  specified,  the  class  -NoSuchClass-  (which  should  have  no 
defaults)  is  used. 

Options 

appres  supports  the  following  command  line  option: 

-xrm  resource 

Specifies  that,  in  addition  to  the  current  application  resources,  appres  should 
return  the  resource  specified  as  an  argument  to  -xrm,  if  that  resource 
would  apply  to  the  classname  or  instancename.  You  must  specify  both 
a classname  and  an  instancename  in  order  to  use  the  -xrm  option. 
(Note  that  -xrm  does  not  actually  load  any  resources.) 

Without  any  arguments,  appres  returns  those  resources  that  might  apply  to  any  application  (for 
example,  those  beginning  with  an  asterisk  in  your  Xresources  file). 

See  Also 

X,  xrdb,  listres 

Author 

Jim  Fulton,  MIT  X Consortium. 
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\ 


Name 

bdftosnf  - BDF  to  SNF  font  compiler  for  XI 1. 

Syntax 

bdftosnf  [options]  bdf_f He 

Description 

bdftosnf  reads  a Bitmap  Distribution  Format  (BDF)  font  from  the  specified  file  (or  from  stan- 
dard input  if  no  file  is  specified)  and  writes  an  XI 1 Server  Natural  Format  (SNF)  font  to  stan- 
dard output. 

Options 

-pnumber 

-unumber 

-m 
-1 
-M 
-L 
-w 

-W 

-t 
-i 

See  Also 

X,  Xserver,  Bitmap  Distribution  Format  2.1 


Forces  the  glyph  padding  to  a specific  number.  The  legal  values  are  1,2, 4, 
and  8. 

Forces  the  scanline  unit  padding  to  a specific  number.  The  legal  values  are 
1, 2,  and  4. 

Forces  the  bit  order  to  most  significant  bit  first. 

Forces  the  bit  order  to  least  significant  bit  first. 

Forces  the  byte  order  to  most  significant  byte  first. 

Forces  the  byte  order  to  least  significant  byte  first. 

Prints  warnings  if  the  character  bitmaps  have  bits  set  to  one  outside  of  their 
defined  widths. 

Prints  warnings  for  characters  with  an  encoding  of  -1;  the  default  is  to  silently 
ignore  such  characters. 

Expands  glyphs  in  “terminal-emulator”  fonts  to  fill  the  bounding  box. 
Suppresses  computation  of  correct  ink  metrics  for  “terminal-emulator”  fonts. 
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Name 

bitmap,  bmtoa,  atobm  - system  bitmap  editor  and  conversion  utilities. 

Syntax 

bitmap  [options]  filename  [WIDTHxHEIGHT] 
bmtoa  [options]  filename 
atobm  [options]  filename 

Description 

bitmap  allows  you  to  create  and  edit  small  bitmaps  which  you  can  use  to  create  backgrounds, 
icons,  and  pointers.  A bitmap  is  a grid  of  pixels,  or  picture  elements,  each  of  which  is  white, 
black,  or,  in  the  case  of  color  displays,  a color. 

The  bmtoa  and  atobm  filters  convert  bitmap  files  to  and  from  ASCII  strings.  They  are  most 
commonly  used  to  quickly  print  out  bitmaps  and  to  generate  versions  for  inclusion  in  text.  The 
bmtoa  and  atobm  programs  are  available  in  the  standard  distribution  of  X as  of  Release  3. 

The  window  that  bitmap  creates  has  three  sections  (see  Figure  6-1  in  Part  One  of  this  guide). 
The  largest  section  is  the  checkerboard  grid,  which  is  a magnified  version  of  the  bitmap  you  are 
editing.  Squares  on  the  grid  can  be  set,  cleared,  or  inverted  directly  with  the  buttons  on  the 
pointer.  A menu  of  higher  level  operations,  such  as  drawing  lines  and  circles,  is  provided  to  the 
right  of  the  grid.  You  can  invoke  these  menu  commands  by  clicking  with  any  mouse  button. 
Beneath  the  menu  commands  is  an  actual  size  picture  of  the  bitmap  you  are  editing;  below  this 
is  an  inverted  version  of  the  same  bitmap.  Each  time  the  grid  changes,  the  same  change  occurs 
in  the  actual-size  bitmap  and  its  inverse. 

If  the  bitmap  is  to  be  used  for  defining  a cursor,  one  of  the  squares  in  the  image  may  be  desig- 
nated as  the  hot  spot.  This  determines  where  the  cursor  is  actually  pointing.  For  cursors  with 
sharp  tips  (such  as  arrows  or  fingers),  this  is  usually  at  the  end  of  the  tip;  for  symmetric  cursors 
(such  as  crosses  or  bullseyes),  this  is  usually  at  the  center. 

Bitmaps  are  stored  as  small  C code  fragments  suitable  for  including  in  applications.  They  pro- 
vide an  array  of  bits  as  well  as  symbolic  constants  giving  the  width,  height,  and  hot  spot  (if 
specified)  that  may  be  used  in  creating  cursors,  icons,  and  tiles. 

The  WIDTHxHEIGHT  argument  gives  the  size  to  use  when  creating  a new  bitmap  (the  default 
is  16x6).  Existing  bitmaps  are  always  edited  at  their  current  size. 

If  the  bitmap  window  is  resized  by  the  window  manager,  the  size  of  the  squares  in  the  grid  will 
shrink  or  enlarge  to  fit. 

Options:  bitmap 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  on  which  to  create  the  bit- 
map window,  host  specifies  which  machine  to  create  the  bitmap  window 
on,  server  specifies  the  server  number,  and  screen  specifies  the  screen 
number.  For  example: 
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bitmap  -display  your_node:0. 1 

creates  a bitmap  window  on  screen  1 of  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary 
in  all  cases. 

-geometry  geometry 

The  bitmap  is  created  with  the  specified  size  and  location  determined  by  the 
supplied  geometry  specification.  The  -geometry  option  can  be  (and  often 
is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins  with  “g.” 
The  argument  to  the  geometry  option  ( geometry ) has  the  form  widthx- 
height±xoff±yoff.  If  you  do  not  specify  the  geometry,  bitmap  asks  you 
for  window  placement  when  it  starts  up.  See  Window  Geometry  in  Chapter  8 
of  this  guide  for  details. 

Prints  a brief  description  of  the  allowable  options. 

Specifies  the  border  width  in  pixels  of  the  bitmap  window.  Default  is  3 pix- 
els. 

Specifies  the  font  to  be  used  in  the  command  buttons  (refer  to  the  Menu  Com- 
mands section  below).  Default  is  fixed,  a 6x13  pixel,  mono-spaced  font. 

Specifies  the  color  to  be  used  for  the  foreground.  Default  is  black. 

Specifies  the  color  to  be  used  for  the  background.  Default  is  white. 

Specifies  the  color  to  be  used  for  highlighting. 

Specifies  the  color  to  be  used  for  the  window  border. 

Specifies  the  color  to  be  used  for  the  pointer  (mouse).  Default  is  black. 

-name  variable 

Specifies  the  variable  name  to  be  used  when  writing  out  the  bitmap  file.  The 
default  is  to  use  the  basename  of  the  filename  command  line  argument 

-nodashed  Specifies  that  the  grid  lines  in  the  bitmap  window  are  drawn  as  solid  lines  not 
as  dashed  lines.  Default  is  dashed  lines.  On  some  servers,  dashed  lines  are 
significantly  slower. 

WIDTHxHEIGHT 

Two  numbers,  separated  by  the  letter  “x",  which  specify  the  size  of  the 
checkerboard  grid  within  the  bitmap  window  (e.g.,  9x13).  The  first  number  is 
the  grid’s  width;  the  second  number  is  its  height  Default  is  16x16. 


-help 

-bw 

number 

-f  n 

font 

-fg 

color 

-bg 

color 

-hi 

color 

-bd 

color 

-ms 

color 

Options:  bmtoa 

The  bmtoa  conversion  program  accepts  the  following  options: 

-chars  cc  Specifies  the  pair  of  characters  to  use  in  the  string  version  of  the  bitmap.  The 
first  character  is  used  for  0 bits  and  the  second  character  is  used  for  1 bits. 
The  default  is  to  use  dashes  (-)  for  0’s  and  number  signs  (#)  for  l’s. 
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Options:  atobm 

The  atobm  conversion  program  accepts  the  following  options: 

-chars  cc  Specifies  the  pair  of  characters  to  use  when  converting  string  bitmaps  into 
arrays  of  numbers.  The  first  character  represents  a 0 bit  and  the  second  char- 
acter represents  a 1 bit.  The  default  is  to  use  dashes  (-)  for  0’s  and  number 
signs  (#)  for  1 ’s. 

-name  variable 

Specifies  the  variable  name  to  be  used  when  writing  out  the  bitmap  file.  The 
default  is  to  use  the  basename  of  the  filename  command  line  argument  or 
leave  it  blank  if  the  standard  input  is  read. 

-xhot  number 

Specifies  the  X coordinate  of  the  hot  spot.  Only  positive  values  are  allowed. 
By  default,  no  hot  spot  information  is  included. 

-yhot  number 

Specifies  the  Y coordinate  of  the  hot  spot  Only  positive  values  are  allowed. 
By  default,  no  hot  spot  information  is  included. 

Changing  Grid  Squares 

Grid  squares  may  be  set,  cleared,  or  inverted  by  pointing  to  them  and  clicking  one  of  the  but- 
tons indicated  below.  Multiple  squares  can  be  changed  at  once  by  holding  the  button  down  and 
dragging  the  cursor  across  them.  Set  squares  are  filled  and  represent  l’s  in  the  bitmap;  clear 
squares  are  empty  and  represent  0’s. 

Button  1 (usually  the  left) 

Changes  one  or  more  grid  squares  to  the  foreground  color  and  sets  the  corre- 
sponding bits  in  the  bitmap  to  1. 

Button  2 (usually  the  middle) 

Inverts  one  or  more  grid  squares.  The  corresponding  bit  or  bits  in  the  bitmap 
are  inverted  (l’s  become  0’s  and  0’s  become  l’s). 

Button  3 (usually  the  right) 

Changes  one  or  more  grid  squares  to  the  background  color  and  sets  the  corre- 
sponding bits  in  the  bitmap  to  0. 


Menu  Commands 

To  make  defining  shapes  easier,  bitmap  provides  13  commands  for  drawing  whole  sections  of 
the  grid  at  once,  two  commands  for  manipulating  the  hot  spot,  and  two  commands  for  updating 
the  bitmap  file  and  exiting.  A command  button  for  each  of  these  operations  is  located  to  the 
right  of  the  grid. 

Several  of  the  commands  operate  on  rectangular  portions  of  the  grid.  These  areas  are  selected 
after  the  command  button  is  pressed  by  moving  the  cursor  to  the  upper  left  square  of  the  desired 
area,  pressing  a pointer  button,  dragging  the  cursor  to  the  lower  right  hand  comer  (with  the  but- 
ton still  pressed),  and  then  releasing  the  button.  The  command  may  be  aborted  by  pressing  any 
other  button  while  dragging  or  by  releasing  outside  the  grid. 


X Window  System  User’s  Guide 


273 


Reference  Pages 


bitmap 


(continued) 


System  Bitmap  Editor 


To  invoke  a command,  move  the  pointer  over  that  command  and  click  any  button. 

The  following  command  descriptions  assume  that  black  is  the  foreground  color  and  white  is  the 
background  color  (the  defaults). 

Clear  All  Turns  all  the  grid  squares  white  and  sets  all  bitmap  bits  to  0.  This  is  irrevers- 


Set  All 

ible,  so  invoke  it  with  caution. 

Turns  all  the  grid  squares  black  and  sets  all  bitmap  bits  to  1.  This  is  also  irre- 
versible, so  invoke  it  with  caution. 

Clear  Area 

Clears  a rectangular  area  of  the  grid,  turning  it  white  and  setting  the  corre- 
sponding bitmap  to  0.  After  you  click  on  this  command,  the  cursor  turns  into 
a comer  cursor  representing  the  upper-left  comer  of  the  area  you  want  to 
clear.  Press  and  hold  down  any  mouse  button  while  moving  the  mouse  to  the 
lower-right  comer  of  the  area  you  want  to  clear,  then  release  the  button. 

While  you  are  holding  down  the  button,  the  selected  area  is  covered  with  X’s, 
and  the  cursor  changes  to  a lower-right  comer  cursor.  If  you  now  wish  to 
abort  the  command  without  clearing  an  area,  either  press  another  mouse  but- 
ton, move  the  cursor  outside  the  grid,  or  move  the  cursor  to  the  left  of  or 
above  the  left-comer. 

Set  Area 

Turns  a rectangular  area  of  the  grid  black  and  sets  the  corresponding  bitmap 
bits  to  1.  It  works  the  same  way  as  the  Clear  Area  command. 

Invert  Area 

Inverts  rectangular  area  of  the  grid.  It  works  the  same  way  as  the  Clear  Area 
command. 

Copy  Area 

Copies  a rectangular  area  from  one  part  of  the  grid  to  another.  First,  you 
select  the  rectangle  to  be  copied,  in  the  manner  described  under  Clear  Area 
above. 

Move  Area 

Once  you  have  selected  the  area  to  copy,  the  cursor  changes  to  an  upper-left 
comer  cursor.  When  you  press  a mouse  button,  a destination  rectangle  over- 
lays the  grid;  moving  the  mouse  while  holding  down  the  button  moves  this 
destination  rectangle.  The  copy  occurs  when  you  release  the  button.  To  can- 
cel the  copy,  move  the  mouse  outside  the  grid  and  then  release  the  button. 

Works  identically  to  Copy  Area,  except  it  clears  the  source  rectangle  after 
copying  to  the  destination. 

Overlay  Area 

Lays  a rectangular  area  from  one  part  of  the  grid  over  a rectangular  area  in 
another  part  of  the  grid.  Select  the  area  as  described  under  Clear  Area.  Over- 
lay is  not  a pixel  for  pixel  replacement:  those  pixels  that  are  clear  (bitmap 
bits  set  to  0)  allow  those  pixels  that  are  set  (bitmap  bits  set  to  1)  to  show 
through  the  overlay. 
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Line 

Circle 

Filled  Circle 

Flood  Fill 

Set  Hot  Spot 

Clear  Hot  Spot 
Write  Output 

Quit 


Draws  a line  between  two  points.  When  you  select  this  menu  option,  the  cur- 
sor changes  to  a dot  shape.  Position  the  cursor  over  the  first  point  of  the  line 
you  want  to  draw  and  click  any  mouse  button.  Then  position  the  cursor  over 
the  end  point  of  the  line  and  click  any  mouse  button.  A black  line  is  drawn 
between  the  two  points. 

Draws  a circle.  When  you  select  this  menu  option,  the  cursor  changes  to  a 
dot  shape.  First,  position  the  cursor  over  the  point  you  want  to  specify  as  the 
center  and  click  any  mouse  button.  Then  position  the  cursor  over  a point  you 
want  to  specify  as  the  radius  and  click  any  mouse  button.  A black  circle  is 
drawn. 

Draws  a filled  circle  when  you  specify  the  center  and  radius  of  the  circle  as 
with  Circle. 

Fills  all  clear  squares  in  a closed  shape  you  specify.  When  you  select  this 
menu  option,  the  cursor  changes  to  a dot  shape.  Click  on  any  clear  square 
inside  the  shape  you  want  to  fill  and  all  clear  squares  are  filled  out  to  the  bor- 
der of  the  closed  shape.  If  the  shape  is  not  closed,  the  entire  grid  will  be 
filled. 

Designates  a point  on  the  bitmap  as  the  “hot  spot”  If  a program  is  using  your 
bitmap  as  a cursor,  the  hot  spot  indicates  which  point  on  the  bitmap  is  the 
“actual”  location  of  the  cursor.  For  instance,  if  your  cursor  is  an  arrow,  the 
hot  spot  could  be  the  tip  of  the  arrow;  if  your  cursor  is  a cross,  the  hot  spot 
should  be  where  the  perpendicular  lines  intersect. 

Removes  any  hot  spot  that  was  defined  for  this  bitmap. 

Writes  the  current  bitmap  value  to  the  file  specified  in  the  command  line.  If 
the  file  already  exists,  the  original  file  is  first  renamed  to  filename ~ (in  the 
manner  of  emacs(  1)  and  other  text  editors). 

If  either  the  renaming  or  the  writing  cause  an  error,  a dialog  box  will  appear 
asking  if  you  want  to  write  the  file  /tmp/filename  instead.  If  you  say  yes,  all 
future  Write  Output  commands  are  written  to  /tmp/filename  as  well.  See  File 
Format  below  for  the  format  of  the  output  file. 

Exits  the  bitmap  program.  If  you  have  edited  the  bitmap  and  have  not 
invoked  Write  Output,  or  you  have  edited  since  the  last  time  you  invoked  Write 
Output,  a dialog  window  appears,  asking  if  you  want  to  save  changes  before 
quitting.  “Yes”  does  a Write  Output  before  exiting.  “No”  just  exits,  losing  the 
edits.  “Cancel”  means  you  decided  not  to  quit  after  all  and  you  can  continue 
with  your  editing. 

You  can  also  terminate  bitmap  by  typing  Ctrl-C  or  q anywhere  in  the  window. 
If  you  have  edited  the  bitmap  and  have  not  invoked  Write  Output,  a dialog 
window  appears,  asking  if  you  want  to  save  changes  before  quitting. 
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File  Format 

The  Write  Output  command  stores  bitmaps  as  simple  C program  fragments  that  can  be  compiled 
into  programs,  referred  to  by  X Toolkit  pixmap  resources,  manipulated  by  other  programs  (see 
xsetroot),  or  read  in  using  utility  routines  in  the  various  programming  libraries.  The  width  and 
height  of  the  bitmap  as  well  as  the  hot  spot,  if  specified,  are  written  as  preprocessor  symbols  at 
the  start  of  the  file.  The  bitmap  image  is  then  written  out  as  an  array  of  characters: 

♦define  name_width  11 
♦define  name_height  5 
♦define  name_x_ hot  5 
♦define  name jy_hot  2 

static  char  name_bits[]  = { 

0x91,  0x04,  Oxca,  0x06,  0x84, 

0x04,  0x8a,  0x04,  0x91,  0x04 

} ; 

The  variables  ending  with  _x_hot  and  _y_hot  are  optional;  they  must  be  present  only  if  a 
hot  spot  has  been  defined  for  this  bitmap.  The  other  variables  must  be  present. 

In  place  of  name , the  five  variables  are  prefixed  with  a string  derived  from  the  name  of  the  file 
specified  on  the  original  command  line.  Any  directories  are  stripped  off  the  front  of  the 
filename  and  any  suffix  (including  the  preceding  period)  is  stripped  off  the  end.  Any 
remaining  non-alphabetic  characters  are  replaced  with  underscores. 

For  example,  invoking  bitmap  with  filename  /usr/include/bitmapsl cross. bitmap  produces  a file 
with  variable  names  cross_width , cross_height,  and  cross_bits  (and 
cross_x_hot  and  cross_y_hot , if  a hot  spot  is  defined). 

Each  character  in  the  the  array  contains  8 bits  from  one  row  of  the  image  (rows  are  padded  out 
at  the  end  to  a multiple  of  8 to  make  this  is  possible).  Rows  are  written  out  from  left  to  right 
and  top  to  bottom.  The  first  character  of  the  array  holds  the  leftmost  8 bits  of  top  line,  and  the 
last  character  holds  the  right  most  8 bits  (including  padding)  of  the  bottom  line.  Within  each 
character,  the  leftmost  bit  in  the  bitmap  is  the  least  significant  bit  in  the  character. 

This  process  can  be  demonstrated  visually  by  splitting  a row  into  words  containing  8 bits  each, 
reversing  the  bits  each  word  (since  Arabic  numbers  have  the  significant  digit  on  the  right  and 
images  have  the  least  significant  bit  on  the  left),  and  translating  each  word  from  binary  to  hexa- 
decimal. 


In  the  following  example,  the  array  of  l’s  and  O’ s on  the  left  represents  a bitmap  containing  5 
rows  and  1 1 columns  that  spells  XI 1.  To  its  right  is  is  the  same  array  split  into  8 bit  words  with 
each  row  padded  with  0’s  so  that  it  is  a multiple  of  8 in  length  (16): 


10001001001 

01010011011 

00100001001 

01010001001 

10001001001 


10001001  00100000 
01010011  01100000 
00100001  00100000 
01010001  00100000 
10001001  00100000 


Reversing  the  bits  in  each  word  of  the  padded,  split  version  of  the  bitmap  yields  the  left  hand 
figure  below.  Interpreting  each  word  as  hexadecimal  number  yields  the  array  of  numbers  on 
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the  right: 


10010001 

00000100 

0x91 

0x04 

11001010 

00000110 

Oxca 

0x06 

10000100 

00000100 

0x84 

0x04 

10001010 

00000100 

0x8a 

0x04 

10010001 

00000100 

0x91 

0x04 

The  character  array  can  then  be  generated  by  reading  each  row  from  left  to  right,  top  to  bottom: 

static  char  na/ne_bits  [ ] = { 

0x91,  0x04,  Oxca,  0x06,  0x84, 

0x04,  0x8a,  0x04,  0x91,  0x04 

} ; 

The  bmtoa  program  may  be  used  to  convert  bitmap  files  into  arrays  of  characters  for  printing  or 
including  in  text  files.  The  atobm  program  can  be  used  to  convert  strings  back  to  bitmap  for- 
mat. 

Using  Bitmaps  in  Programs 

To  define  a bitmap  or  pointer  in  an  X program,  include  (# include ) a bitmap  file  and  refer  to  its 
variables.  For  instance,  to  use  a pointer  defined  in  the  files  this.cursor  and  thisjnask.cursor, 
write: 

♦include  "this.cursor" 

♦include  "this_mask . cursor " 

XColor  foreground  background; 

Pixmap  source  = XCreateBitmapFromData  (display,  drawable,  this  bits, 
this_width,  this_height ) ; 

Pixmap  mask  = XCreateBitmapFromData  (display,  drawable,  this_mask_bits, 
this_mask_width,  this_mask_height ) ; 

Cursor  cursor  = XCreatePixmapCursor  (display,  source,  mask,  foreground, 
background,  this_x_hot,  this_y_hot) ; 

where  .foreground  and  background  are  XColor  values. 

Additional  routines  are  available  for  reading  in  bitmap  files  and  returning  the  data  in  the  file  in 
Bitmap  (single-plane  Pixmap  for  use  with  routines  that  require  stipples)  or  full  depth  Pixmaps 
(often  used  for  window  backgrounds  and  borders).  Applications  writers  should  be  careful  to 
understand  the  difference  between  Bitmaps  and  Pixmaps  so  that  their  programs  function  cor- 
rectly on  color  and  monochrome  displays. 

For  backward  compatibility,  bitmap  will  also  accept  X10  format  bitmap  files.  However,  when 
the  file  is  written  out  again  it  will  be  in  X 1 1 format. 

Resources 

The  bitmap  program  accepts  the  following  resources.  The  foreground,  background,  and  high- 
light colors  are  ignored  unless  you  specify  new  values  for  all  three  options. 

Background  Determines  the  window’s  background  color.  Bits  which  are  0 in  the  bitmap 
are  displayed  in  this  color.  Default  is  white. 
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BodyFont  Determines  the  text  font.  Default  is  fixed,  a 6x13  pixel  mono-spaced  font. 
BorderColor  Determines  the  color  of  the  border.  Default  is  black. 


BorderWidth  Determines  the  border  width.  Default  is  2 pixels. 


Dashed  Determines  whether  dashed  or  solid  lines  are  used  for  the  bitmap  grid.  (On 

specifies  dashed  lines,  off  specifies  solid.)  Default  is  on.  (Available  as  of 
Release  4.) 


Foreground  Determines  the  foreground  color.  Bits  which  are  1 in  the  bitmap  are 
displayed  in  this  color.  Default  is  black. 

Highlight  Determines  the  highlight  color,  bitmap  uses  this  color  to  show  the  hot  spot 
and  to  indicate  rectangular  areas  that  are  affected  by  the  Move  Area,  Copy 
Area,  Set  Area,  Clear  Area,  and  Invert  Area  commands.  If  a highlight  color  is 
not  given,  then  bitmap  highlights  by  inverting.  For  example,  if  you  have  a 
black  rectangular  area  selected  for  a move,  white  X’s  appear  in  the  rectangle. 

Mouse  Determines  the  pointer’s  color.  Default  is  black. 


Geometry  Determines  the  size  and  location  of  the  bitmap  window. 

Dimensions  Determines  the  WIDTHxHEIGHT  of  the  checkerboard  grid  within  the  bitmap 
window.  Default  is  16x16. 


Files 

Many  standard  bitmaps  can  be  found  in  the  directory  lusr/include/Xl  1 /bitmaps . 

Bugs 

The  old  command  line  arguments  aren’t  consistent  with  other  X programs. 

If  you  move  the  pointer  too  fast  while  holding  a pointer  button  down,  some  squares  may  be 
missed.  This  is  caused  by  limitations  in  how  frequently  the  X server  can  sample  the  pointer 
location. 

There  is  no  way  to  write  to  a file  other  than  the  one  specified  on  the  command  line. 

There  is  no  way  to  change  the  size  of  the  bitmap  once  the  program  has  started. 

There  is  no  Undo  command. 

Author 

bitmap  by  Ron  Newman,  MIT  Project  Athena;  bmtoa  and  atobm  by  Jim  Fulton,  MIT  X Consor- 
tium. 

See  Also 

Chapter  6 of  this  guide;  Volume  One,  Xlib  Programmer’ s Guide;  XmuReadBitmapDataFrom- 
File. 
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Name 

listres  - list  resources  in  widgets. 

Syntax 

listres  [ options ] 


Description 

Available  as  of  Release  4,  the  listres  program  generates  a list  of  a widget’s  resource  database. 
The  class  in  which  each  resource  is  first  defined,  the  instance  and  class  name,  and  the  type  of 
each  resource  is  listed.  If  no  specific  widgets  or  the  -all  switch  are  given,  a two-column  list 
of  widget  names  and  their  class  hierarchies  is  printed. 


Options 

listres  accepts  all  of  the  standard  X Toolkit  command  line  options,  along  with  the  following: 


-all 


Indicates  that  listres  should  print  information  for  all  known  widgets  and 
objects. 


-nosuper  Indicates  that  resources  that  are  inherited  from  a superclass  should  not  be 
listed.  This  is  useful  for  determining  which  resources  are  new  to  a subclass. 

-variable  Indicates  that  widgets  should  be  identified  by  the  names  of  the  class  record 
variables  rather  than  the  class  name  given  in  the  variable.  This  is  useful  for 
distinguishing  subclasses  that  have  the  same  class  name  as  their  superclasses. 

-top  name  Specifies  the  name  of  the  widget  to  be  treated  as  the  top  of  the  hierarchy. 

Case  is  not  significant,  and  the  name  may  match  either  the  class  variable 
name  or  the  class  name.  The  default  is  core. 

-format  print f_string 

Specifies  the  printf-style  format  string  to  be  used  to  print  out  the  name, 
instance,  class,  and  type  of  each  resource. 


See  Also 

X,  xrdb;  Volume  Four,  X Toolkit  Intrinsics  Programming  Manual’,  Volume  Five,  X Toolkit 
Intrinsics  Reference  Manual’,  appropriate  widget  documents 

Bugs 

On  operating  systems  that  do  not  support  dynamic  linking  of  run-time  routines,  this  program 
must  have  all  of  its  known  widgets  compiled  in.  The  sources  provide  several  tools  for  automat- 
ing this  process  for  various  widget  sets. 

Author 

Jim  Fulton,  MIT  X Consortium. 
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\ 


Name 

mkfontdir  - creates  a fonts.dir  file  for  each  specified  directory  of  font  files. 

Syntax 

mkfontdir  [direct ory-names] 

Description 

For  each  directory  argument,  mkfontdir  reads  all  of  the  font  files  in  the  directory  and  searches 
for  properties  named  “FONT’,  or  (failing  that)  the  name  of  the  file  stripped  of  its  suffix.  These 
are  used  as  font  names,  which  are  written  out  to  the  file  fonts.dir  in  the  directory,  along  with  the 
name  of  the  font  file. 

The  kinds  of  font  files  read  by  mkfontdir  depend  on  configuration  parameters,  but  typically 
include  SNF  (suffix  .snf),  compressed  SNF  (suffix  . snfZ ),  BDF  (suffix  .bdf),  and  compressed 
BDF  (suffix  .bdf. Z).  If  a font  exists  in  multiple  formats,  the  most  efficient  format  will  be  used. 

Font  Name  Aliases 

The  file  fonts.alias,  which  can  be  put  in  any  directory  of  the  font  path,  is  used  to  map  new 
names  to  existing  fonts,  and  should  be  edited  by  hand.  The  format  is  straight  forward  enough, 
two  white-space  separated  columns,  the  first  containing  aliases  and  the  second  containing  font- 
name  patterns. 

When  a font  alias  is  used,  the  name  it  references  is  searched  for  in  the  normal  manner,  looking 
through  each  font  directory  in  turn.  This  means  that  the  aliases  need  not  mention  fonts  in  the 
same  directory  as  the  alias  file. 

To  embed  white-space  in  either  name,  simply  enclose  them  in  double-quote  marks.  To  embed 
double-quote  marks  (or  any  other  character),  precede  them  with  back-slash: 

"magic-alias  with  spaces"  'VfontnameV'  with  quotes" 
regular  alias  fontname 

If  the  string  FILE_NAMES_ALIASES  stands  alone  on  a line,  each  filename  in  the  particular 
directory  (stripped  of  it’s  .snf  suffix)  will  be  used  as  an  alias  for  that  font. 

Usage 

Xserver  looks  for  both  fonts.dir  and  fonts.alias  in  each  directory  in  the  font  path  each  time  the 
font  path  is  set  (see  xset). 

See  Also 

X,  Xserver,  xset 
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Name 

oclock  - display  time  of  day  in  analog  form. 

Syntax 

oclock  [options] 

Description 

Available  as  of  Release  4,  oclock  displays  the  current  time  on  an  analog  display. 

Options 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  display  the 
oclock  window,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 

oclock  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  oclock  window  is  created  with  the  specified  size  and  location  determined 
by  the  supplied  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  widthx- 
hei  gh  t ±xoff±yoff. 

-fg  color  Specifies  a color  for  both  the  hands  and  the  jewel  of  the  clock. 

-bg  color  Specifies  a color  for  the  background. 

-jewel  color 

Specifies  a color  for  the  jewel  on  the  clock. 

-minute  color 

Specifies  a color  for  the  minute  hand  of  the  clock. 

-hour  col  or  Specifies  a color  for  the  hour  hand  of  the  clock. 

-backing  { WhenMapped Always  NotUseful  } 

Selects  an  appropriate  level  of  backing  store. 

-bd  col  or  Specifies  a color  for  the  window  border. 

-bw  pixels  Specifies  a width  in  pixels  for  the  window  border.  As  the  Clock  widget 
changes  its  border  around  quite  a bit,  this  is  most  usefully  set  to  zero. 
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-no shape  Causes  the  clock  not  to  reshape  itself  and  ancestors  to  exactly  fit  the  outline 
of  the  clock. 


Colors 

Although  the  default  colors  for  the  Clock  widget  are  black  and  white,  the  widget  was  designed 
in  color;  unfortunately,  the  toolkit  makes  specifying  these  colors  in  a device-independent  man- 
ner difficult.  If  you  want  to  see  the  correct  colors,  add  the  following  lines  to  your  resource  file: 

Clock*Background:  grey 
Clock*BorderColor : light  blue 
Clock*hour:  yellow 
Clock* jewel:  yellow 
Clock*minute : yellow 


See  Also 

X;  Volume  Four,  X Toolkit  Intrinsics  Programming  Manual’,  Volume  Five,  X Toolkit  Intrinsics 
Reference  Manual 


Author 

Keith  Packard,  MIT  X Consortium. 
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Name 

resize  - utility  to  set  TERMCAP  and  terminal  settings  to  current  window  size. 

Syntax 

resize  [ options ] 

Description 

resize  prints  a shell  command  for  setting  the  TERM  and  TERMCAP  environment  variables  to 
indicate  the  current  size  of  the  xterm  window  from  which  the  command  is  run.  For  this  output 
to  take  effect,  resize  must  either  be  evaluated  as  part  of  the  command  line  (usually  done  with  a 
shell  alias  or  function)  or  else  redirected  to  a file  which  can  then  be  read  in.  From  the  C shell 
(usually  known  as  / binlcsh ),  the  following  alias  could  be  defined  in  the  user’s  . cshrc : 

% alias  rs  'set  noglob;  eval  'resize';  unset  noglob' 

After  resizing  the  window,  the  user  would  type: 

% rs 

Users  of  versions  of  the  Bourne  shell  (usually  known  as  Ibin/sh ) that  don’t  have  command  func- 
tions will  need  to  send  the  output  to  a temporary  file  and  the  read  it  back  in  with  the  com- 
mand: 

$ resize  >/tmp/out 
$ . /tmp/out 

Options 

The  following  options  may  be  used  with  resize: 

-u  Indicates  that  Bourne  shell  commands  should  be  generated  even  if  the  user’s 

current  shell  isn’t  Ibin/sh. 

-c  Indicates  that  C shell  commands  should  be  generated  even  if  the  user’s  cur- 

rent shell  isn’t  Ibin/csh. 

-s [rows  columns] 

Indicates  that  that  Sun  console  escape  sequences  will  be  used  instead  of  the 
special  xterm  escape  code.  If  rows  and  columns  are  given,  resize  will  ask  the 
xterm  to  resize  itself.  However,  the  window  manager  may  choose  to  disallow 
the  change. 

The  -u  or  -c  must  appear  to  the  left  of  -s  if  both  are  specified. 

Files 

letc/termcap  for  the  base  termcap  entry  to  modify. 

7. cshrc  user’s  alias  for  the  command. 

See  Also 

csh(l),  tset(l),  xterm 
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Reset  Terminal  for  Window  Size 


Bugs 

There  should  be  some  global  notion  of  display  size;  termcap  and  terminfo  need  to  be  rethought 
in  the  context  of  window  systems.  (Fixed  in  4.3BSD  and  Ultrix-32  1.2.) 

Authors 

Mark  Vandevoorde  (MIT-Athena),  Edward  Moy  (Berkeley). 

Copyright  (c)  1984,  1985  by  Massachusetts  Institute  of  Technology. 

See  X for  a complete  copyright  notice. 
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Name 

showsnf  - print  contents  of  an  SNF  file  to  standard  output 

Syntax 

showsnf  [options]  snf_file 

Description 

showsnf  displays  the  contents  of  font  files  in  the  Server  Natural  Format  produced  by  bdftosnf. 
It  is  usually  only  used  to  verify  that  a font  file  hasn’t  been  corrupted  or  to  convert  the  individual 
glyphs  into  arrays  of  characters  for  proofreading  or  for  conversion  to  some  other  format. 

Options 

-v 

-g 

-m 
-1 
-M 
-L 

—pnumber 
-u number 

See  Also 

X,  Xserver,  bdftosnf 

Bugs 

There  is  no  way  to  just  print  out  a single  glyph. 


Indicates  that  character  bearings  and  sizes  should  be  printed. 
Indicates  that  character  glyph  bitmaps  should  be  printed. 

Indicates  that  the  bit  order  of  the  font  is  most  significant  bit  first. 
Indicates  that  the  bit  order  of  the  font  is  least  significant  bit  first. 
Indicates  that  the  byte  order  of  the  font  is  most  significant  byte  first. 
Indicates  that  the  byte  order  of  the  font  is  least  significant  byte  first. 
Specifies  the  glyph  padding  of  the  font 
Specifies  the  scanline  unit  of  the  font 
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Name 

twm  - Tab  Window  Manager  for  the  X Window  System. 

Syntax 

twm  [options] 

Description 

twm  is  a window  manager  for  the  X Window  System.  It  has  been  made  the  official  window 
manager  in  the  standard  distribution  in  Release  4.  twm  provides  titlebars,  shaped  windows, 
several  forms  of  icon  management,  user-defined  macro  functions,  click-to-type  and  pointer- 
driven  keyboard  focus,  and  user- specified  key  and  pointer  button  bindings. 

This  program  is  usually  started  by  the  user’s  session  manager  or  startup  script.  When  used  from 
xdm  or  xinit  without  a session  manager,  twm  is  frequently  executed  in  the  foreground  as  the  last 
client.  When  run  this  way,  exiting  twm  causes  the  session  to  be  terminated  (i.e.,  logged  out). 

By  default,  application  windows  are  surrounded  by  a “frame”  with  a titlebar  at  the  top  and  a 
special  border  around  the  window.  The  titlebar  contains  the  window’s  name,  a rectangle  that  is 
lit  when  the  window  is  receiving  keyboard  input,  and  function  boxes  known  as  “titlebuttons” 
at  the  left  and  right  edges  of  the  titlebar. 

Pressing  pointer  Buttonl  (usually  the  left-most  button  unless  it  has  been  changed  with  xmod- 
map)  on  a titlebutton  will  invoke  the  function  associated  with  the  button.  In  the  default  inter- 
face, windows  are  iconified  by  clicking  (pressing  and  then  immediately  releasing)  the  left 
titlebutton  (which  looks  like  a small  X).  Conversely,  windows  are  deiconified  by  clicking  in 
the  associated  icon  or  entry  in  the  icon  manager  (see  description  of  the  variable  Showicon- 
Manager  and  of  the  function  f . showiconmgr). 

Windows  are  resized  by  pressing  the  right  titlebutton  (which  resembles  group  of  nested 
squares),  dragging  the  pointer  over  edge  that  is  to  be  moved,  and  releasing  the  pointer  when  the 
outline  of  the  window  is  the  desired  size.  Similarly,  windows  are  moved  by  pressing  in  the  title 
or  highlight  region,  dragging  a window  outline  to  the  new  location,  and  then  releasing  when  the 
outline  is  in  the  desired  position.  Just  clicking  in  the  title  or  highlight  region  raises  the  window 
without  moving  it. 

When  new  windows  are  created,  twm  will  honor  any  size  and  location  information  requested  by 
the  user  (usually  through  -geometry  command  line  argument  or  resources  for  the  individual 
applications).  Otherwise,  an  outline  of  the  window’s  default  size,  its  titlebar,  and  lines  dividing 
the  window  into  a 3x3  grid  that  track  the  pointer  are  displayed.  Clicking  pointer  Buttonl  will 
position  the  window  at  the  current  position  and  give  it  the  default  size.  Pressing  pointer  But- 
ton2  (usually  the  middle  pointer  button)  and  dragging  the  outline  will  give  the  window  its  cur- 
rent position  but  allow  the  sides  to  be  resized  as  described  above.  Clicking  pointer  Button3 
(usually  the  right  pointer  button)  will  give  the  window  its  current  position  but  attempt  to  make 
it  long  enough  to  touch  the  bottom  the  screen. 

Options 

twm  accepts  the  following  command  line  options: 
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-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

twm  -display  your_node:  0 . 0 

specifies  screen  0 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-s  Indicates  that  only  the  default  screen  (as  specified  by  -display  or  by  the 

DISPLAY  environment  variable)  should  be  managed.  By  default,  twm  will 
attempt  to  manage  all  screens  on  the  display. 

f twmfile  Specifies  the  name  of  the  startup  file  to  use.  By  default,  twm  will  look  in  the 
user  s home  directory  for  files  named  .twmrc.num  (where  num  is  a screen 
number)  or  .twmrc. 

“v  Indicates  that  twm  should  print  error  messages  whenever  an  unexpected  X 

Error  event  is  received.  This  can  be  useful  when  debugging  applications  but 
can  be  distracting  in  regular  use. 

Customization 

Much  of  twm’s  appearance  and  behavior  can  be  controlled  by  providing  a startup  file  in  one  of 
the  following  locations  (searched  in  order  for  each  screen  being  managed  when  twm  begins): 

$H OM EL  twmrc.  screennumber 

The  screennumber  is  a small  positive  number  (e.g.  0, 1,  etc.)  representing  the 
screen  number  (e.g.  the  last  number  in  the  DISPLAY  environment  variable 
ho st '.display num. screennum)  that  would  be  used  to  contact  that  screen  of  the 
display.  This  is  intended  for  displays  with  multiple  screens  of  differing  visual 
types. 

$HOMEI. twmrc  This  is  the  usual  name  for  an  individual  user’s  startup  file. 

/ usr/ lib/Xl  1 / twm/ system . twmrc 

If  neither  of  the  preceding  files  are  found,  twm  will  look  in  this  file  for  a 
default  configuration.  This  is  often  tailored  by  the  site  administrator  to  pro- 
vide convenient  menus  or  familiar  bindings  for  novice  users. 

If  no  startup  files  are  found,  twm  will  use  the  built-in  defaults  described  above.  The  only 
resource  used  by  twm  is  bitmapFilePath  for  a colon-separated  list  of  directories  to  search 
when  looking  for  bitmap  files.  (For  more  information,  see  the  Athena  Widgets  manual  and 
xrdb ). 

twm  startup  files  are  logically  broken  up  into  three  types  of  specifications:  variables , bindings, 
and  menus.  The  variables  section  must  come  first  and  is  used  to  describe  the  fonts,  colors,  cur- 
sors, border  widths,  icon  and  window  placement,  highlighting,  autoraising,  layout  of  titles. 
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warping,  use  of  the  icon  manager.  The  bindings  section  usually  comes  second  and  is  used  to 
specify  the  functions  that  should  be  to  be  invoked  when  keyboard  and  pointer  buttons  are 
pressed  in  windows,  icons,  titles,  and  frames.  The  menus  section  gives  any  user-defined  menus 
(containing  functions  to  be  invoked  or  commands  to  be  executed). 

Variable  names  and  keywords  are  case-insensitive.  Strings  must  be  surrounded  by  double 
quote  characters  (e.g.,  “blue”)  and  are  case-sensitive.  A pound  sign  (#)  outside  of  a string 
causes  the  remainder  of  the  line  in  which  the  character  appears  to  be  treated  as  a comment. 

Variables 

Many  of  the  aspects  of  twm' s user  interface  are  controlled  by  variables  that  may  be  set  in  the 
user’s  startup  file.  Some  of  the  options  are  enabled  or  disabled  simply  by  the  presence  of  a par- 
ticular keyword.  Other  options  require  keywords,  numbers,  strings,  or  lists  of  all  of  these. 

Lists  are  surrounded  by  braces  and  are  usually  separated  by  whitespace  or  a newline.  For 
example: 

AutoRaise  { "emacs"  "XTerm"  "Xmh"  } 

or 

AutoRaise 

{ 

"emacs" 

"XTerm" 

"Xmh" 

} 

When  a variable  containing  a list  of  strings  representing  windows  is  searched  (e.g.  to  determine 
whether  or  not  to  enable  autoraise  as  shown  above),  a string  is  considered  to  match  a window  if 
it  is  a case-sensitive  prefix  for  the  window’s  name  name  (given  by  the  WM_NAME  window 
property),  resource  name  or  class  name  (both  given  by  the  WM_CLASS  window  property). 
The  preceding  example  would  enable  autoraise  on  windows  named  “emacs”  as  well  as  any 
xterm  (since  they  are  of  class  XTerm)  or  xmh  windows  (which  are  of  class  Xmh). 

String  arguments  that  are  interpreted  as  filenames  (see  the  Pixmaps,  Cursors,  and  Icon- 
Directory  variables  later  in  this  reference  page)  will  prepend  the  user’s  directory  (specified 
by  the  HOME  environment  variable)  if  the  first  character  is  a tilde  (“).  If,  instead,  the  first  char- 
acter is  a colon  (:),  the  name  is  assumed  to  refer  to  one  of  the  internal  bitmaps  that  are  used  to 
create  the  default  titlebars  symbols:  :xlogo  or  :iconify  (both  refer  to  the  X used  for  the  iconify 
button),  :resize  (the  nested  squares  used  by  the  resize  button),  and  question  (the  question  mark 
used  for  non-existent  bitmap  files). 

The  following  variables  may  be  specified  at  the  top  of  a twm  startup  file.  Lists  of  Window 
name  prefix  strings  are  indicated  by  win_list.  Optional  arguments  are  shown  in  square 
brackets: 

AutoRaise  { win_list  ) 

Specifies  a list  of  windows  that  should  automatically  be  raised  whenever  the 
pointer  enters  the  window.  This  action  can  be  interactively  enabled  or  dis- 
abled on  individual  windows  using  the  function  f . autoraise. 
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AutoRelativeResize 

Indicates  that  dragging  out  a window  size  (either  when  initially  sizing  the 
window  with  pointer  Button2  or  when  resizing  it)  should  not  wait  until  the 
pointer  has  crossed  the  window  edges.  Instead,  moving  the  pointer  automati- 
cally causes  the  nearest  edge  or  edges  to  move  by  the  same  amount.  This 
allows  allows  the  resizing  windows  that  extend  off  the  edge  of  the  screen.  If 
the  pointer  is  in  the  center  of  the  window,  or  if  the  resize  is  begun  by  pressing 
a titlebutton,  twm  will  still  wait  for  the  pointer  to  cross  a window  edge  (to 
prevent  accidents).  This  option  is  particularly  useful  for  people  who  like  the 
press-drag-release  method  of  sweeping  out  window  sizes. 

BorderColor  string  [{  win_color_list  }] 

Specifies  the  default  color  of  the  border  to  be  placed  around  all  non-iconified 
windows,  and  may  only  be  given  within  a WColor  or  WMonochrome  list. 
The  optional  win_color_list  specifies  a list  of  window  and  color  name  pairs 
for  specifying  particular  border  colors  for  different  types  of  windows.  For 
example: 

BorderColor  "gray50" 

{ 

"XTerm"  "red" 

"xmh"  "green" 

} 

The  default  is  black. 

BorderTileBackground  string  [{  wincolorlist  }] 

Specifies  the  default  background  color  in  the  gray  pattern  used  in 
unhighlighted  borders  (only  if  NoHighlight  hasn’t  been  set),  and  may 
only  be  given  within  a Color  or  Monochrome  list.  The  optional  win- 
color  lis  t allows  per- window  colors  to  be  specified.  The  default  is  black. 

BorderTileForeground  string  [{  wincolorlist  )] 

Specifies  the  default  foreground  color  in  the  gray  pattern  used  in 
unhighlighted  borders  (only  if  NoHighlight  hasn’t  been  set),  and  may 
only  be  given  within  a Color  or  Monochrome  list.  The  optional  win- 
colorlist allows  per-window  colors  to  be  specified.  The  default  is  white. 

BorderWidth  pixels 

Specifies  the  width  in  pixels  of  the  border  surrounding  all  client  window 
frames  if  ClientBorderWidth  has  not  been  specified.  This  value  is  also 
used  to  set  the  border  size  of  windows  created  by  twm  (such  as  the  icon  man- 
ager). The  default  is  2. 

Buttonlndent  pixels 

Specifies  the  amount  by  which  titlebuttons  should  be  indented  on  all  sides. 
Positive  values  cause  the  buttons  to  be  smaller  than  the  window  text  and 
highlight  area  so  that  they  stand  out.  Setting  this  and  the  TitleButton- 
BorderWidth  variables  to  0 makes  titlebuttons  be  as  tall  and  wide  as  pos- 
sible. The  default  is  1. 
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ClientBorderWidth 

Indicates  that  border  width  of  a window’s  frame  should  be  set  to  the  initial 
border  width  of  the  window,  rather  than  to  the  value  of  BorderWidth. 

Color  { colors_list  } 

Specifies  a list  of  color  assignments  to  be  made  if  the  default  display  is  cap- 
able of  displaying  more  than  simple  black  and  white.  The  colors_list  is 
made  up  of  the  following  color  variables  and  their  values:  Default- 
Background,  Def aultForeground,  MenuBackground,  Menu- 
Foreground,  MenuTitleBackground,  MenuTitleForeground, 
and  MenuShadowColor. 

The  following  color  variables  may  also  be  given  a list  of  window  and  color 
name  pairs  to  allow  per-window  colors  to  be  specified  (see  BorderColor 
for  details):  BorderColor,  IconManagerHighlight,  Border- 
Tit leBackground,  BorderTit leForeground,  Title- 

Background,  TitleForeground,  IconBackground,  Icon- 
Foreground,  IconBorderColor,  IconManagerBackground,  and 
iconManagerForeground.  For  example: 

Color 
{ 

MenuBackground 
MenuForeground 
BorderColor 
TitleForeground 
Tit leBackground 

} 

All  of  these  color  variables  may  also  be  specified  for  the  Monochrome  vari- 
able, allowing  the  same  initialization  file  to  be  used  on  both  color  and  mono- 
chrome displays. 

ConstrainedMoveTime  milliseconds 

Specifies  the  length  of  time  between  button  clicks  needed  to  begin  a con- 
strained move  operation.  Double  clicking  within  this  amount  of  time  when 
invoking  f .move  will  cause  the  window  only  be  moved  in  a horizontal  or 
vertical  direction.  Setting  this  value  to  0 will  disable  constrained  moves.  The 
default  is  400  milliseconds. 

Cursors  { cursor_list  } 

Specifies  the  glyphs  that  twm  should  use  for  various  pointer  cursors.  Each 
cursor  may  be  defined  either  from  the  Cursor  font  or  from  two  bitmap  files. 
Shapes  from  the  Cursor  font  may  be  specified  directly  as: 

cursorname  "string" 

where  cursorname  is  one  of  the  cursor  names  listed  below,  and  string  is 


"gray50" 
"blue" 
"red"  { ' 
"yellow" 
"blue" 


XTerm"  "yellow"  } 
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the  name  of  a glyph  as  found  in  the  file  /usr/include/Xll/cursorfont.h  (with- 
out the  XC_  prefix).  If  the  cursor  is  to  be  defined  from  bitmap  files,  the 
following  syntax  is  used  instead: 

cursorname  "image"  "mask" 

The  image  and  mask  strings  specify  the  names  of  files  containing  the  glyph 
image  and  mask  in  bitmap  form.  The  bitmap  files  are  located  in  the  same 
manner  as  icon  bitmap  files.  The  following  example  shows  the  default  cursor 
definitions: 

Cursors 
{ 

Frame 
Title 
Icon 
IconMgr 
Move 
Resize 
Menu 
Button 
Wait 
Select 
Destroy 

} 

DecorateTransients 

Indicates  that  transient  windows  (those  containing  a WM_TRAN- 
SIENT_FOR  property)  should  have  titlebars.  By  default,  transients  are  not 
reparented. 

Def  aultBackground  string 

Specifies  the  background  color  to  be  used  for  sizing  and  information  win- 
dows. The  default  is  white. 

Def aultForeground  string 

Specifies  the  foreground  color  to  be  used  for  sizing  and  information  windows. 
The  default  is  black. 

DontlconifyByUnmapping  { win_list  } 

Specifies  a list  of  windows  that  should  not  be  iconified  by  simply  unmapping 
the  window  (as  would  be  the  case  if  iconifyByUnmapping  had  been  set). 
This  is  frequently  used  to  force  some  windows  to  be  treated  as  icons  while 
other  windows  are  handled  by  the  icon  manager. 

DontMoveOf  f Indicates  that  windows  should  not  be  allowed  to  be  moved  off  the  screen.  It 
can  be  overridden  by  the  f . f orcemove  function. 

DontSqueezeTitle  [{  win_list  )] 

Indicates  that  titlebars  should  not  be  squeezed  to  their  minimum  size  as 
described  under  SqueezeTitle  below.  If  the  optional  window  list  is 


" t op_l e f t_a  rrow" 
"top_left_arrow" 
"top_left_arrow" 
"top_left_arrow" 
"f leur" 

"fleur" 

"sb_left_arrow" 

"hand2" 

"watch" 

"dot" 

"pirate" 
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supplied,  only  those  windows  will  be  prevented  from  being  squeezed. 

Forcelcons  Indicates  that  icon  pixmaps  specified  in  the  Icons  variable  should  override 
any  client-supplied  pixmaps. 

FramePadding  pixels 

Specifies  the  distance  between  the  titlebar  decorations  (the  button  and  text) 
and  the  window  frame.  The  default  is  2 pixels. 

IconBackground  string  [{  win_list  )] 

Specifies  the  background  color  of  icons,  and  may  only  be  specified  inside  of  a 
Color  or  Monochrome  list.  The  optional  win_list  is  a list  of  window 
names  and  colors  so  that  per-window  colors  may  be  specified.  See  the 
BorderColor  variable  for  a complete  description  of  the  win_list.  The 
default  is  white. 

IconBorderColor  string  [{  win_list  }] 

Specifies  the  color  of  the  border  used  for  icon  windows,  and  may  only  be 
specified  inside  of  a Color  or  Monochrome  list.  The  optional  win_list 
is  a list  of  window  names  and  colors  so  that  per-window  colors  may  be  speci- 
fied. See  the  BorderColor  variable  for  a complete  description  of  the 
win_list.  The  default  is  black. 

IconBorderWidth  pixels 

Specifies  the  width  in  pixels  of  the  border  surrounding  icon  windows.  The 
default  is  2. 

IconDirectory  string 

Specifies  the  directory  that  should  be  searched  if  if  a bitmap  file  cannot  be 
found  in  any  of  the  directories  in  the  bitmapFilePath  resource. 

IconFont  string 

Specifies  the  font  to  be  used  to  display  icon  names  within  icons.  The  default 
is  8x13. 

IconForeground  string  [{  win_list  }] 

Specifies  the  foreground  color  to  be  used  when  displaying  icons,  and  may 
only  be  specified  inside  of  a Color  or  Monochrome  list.  The  optional 
win_list  is  a list  of  window  names  and  colors  so  that  per-window  colors 
may  be  specified.  See  the  BorderColor  variable  for  a complete  descrip- 
tion of  the  win_li  st.  The  default  is  black. 

Iconif yByUnmapping  [ { win_list  } ] 

Indicates  that  windows  should  be  iconified  by  being  unmapped  without  trying 
to  map  any  icons.  This  assumes  that  the  user  is  will  remap  the  window 
through  the  icon  manager,  the  f .warpto  function,  or  the  TwmWindows 
menu.  If  the  optional  win_list  is  provided,  only  those  windows  will  be 
iconified  by  simply  unmapping.  Windows  that  have  both  this  and  the  Icon- 
ManagerDontShow  options  set  may  not  be  accessible  if  no  binding  to  the 
TwmWindows  menu  is  set  in  the  user’s  startup  file. 
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IconManagerBackground  string  [{  win_list  }] 

Specifies  the  background  color  to  use  for  icon  manager  entries,  and  may  only 
be  specified  inside  of  a Color  or  Monochrome  list.  The  optional 
win_list  is  a list  of  window  names  and  colors  so  that  per- window  colors 
may  be  specified.  See  the  BorderColor  variable  for  a complete  descrip- 
tion of  the  win_lis t.  The  default  is  white. 

IconManagerDontShow [{  win_list  }] 

Indicates  that  the  icon  manager  should  not  display  any  windows.  If  the 
optional  win_list  is  given,  only  those  windows  will  not  be  displayed.  This 
variable  is  used  to  prevent  windows  that  are  rarely  iconified  (such  as  xclock 
or  xload ) from  taking  up  space  in  the  icon  manager. 

IconManagerFont  string 

Specifies  the  font  to  be  used  when  displaying  icon  manager  entries.  The 
default  is  8x13. 

IconManagerForeground  string  [{  win_list  }] 

Specifies  the  foreground  color  to  be  used  when  displaying  icon  manager 
entries,  and  may  only  be  specified  inside  of  a Color  or  Monochrome  list. 
The  optional  win_list  is  a list  of  window  names  and  colors  so  that  per- 
window  colors  may  be  specified.  See  the  BorderColor  variable  for  a com- 
plete description  of  the  win_list.  The  default  is  black. 

IconManagerGeometry  string  [ columns  ] 

Specifies  the  geometry  of  the  icon  manager  window.  The  string  argument 
is  standard  geometry  specification  that  indicates  the  initial  full  size  of  the 
icon  manager.  The  icon  manager  window  is  then  broken  into  columns 
pieces  and  scaled  according  to  the  number  of  entries  in  the  icon  manager. 
Extra  entries  are  wrapped  to  form  additional  rows.  The  default  number  of 
columns  is  1. 

IconManagerHighlight  string[{  win_list  }] 

Specifies  the  border  color  to  be  used  when  highlighting  the  icon  manager 
entry  that  currently  has  the  focus,  and  can  only  be  specified  inside  of  a 
Color  or  Monochrome  list.  The  optional  win_list  is  a list  of  window 
names  and  colors  so  that  per-window  colors  may  be  specified.  See  the 
BorderColor  variable  for  a complete  description  of  the  win_list.  The 
default  is  black. 

IconManagers  { iconmgr_lis t } 

Specifies  a list  of  icon  managers  to  create.  Each  item  in  the  iconmgr_list 
has  the  following  format: 

" winname"  ["iconname"]  "geometry”  columns 

where  winname  is  the  name  of  the  windows  that  should  be  put  into  this  icon 
manager,  iconname  is  the  name  of  that  icon  manager  window  s icon, 
geometry  is  a standard  geometry  specification,  and  columns  is  the  num- 
ber of  columns  in  this  icon  manager  as  described  in 


o 


X Window  System  User’s  Guide 


293 


Reference  Pages 


twm 


(continued) 


Tab  Window  Manager 


IconManagerGeometry.  For  example: 

IconManagers 

{ 

"XTerm"  "=300x5+800+5"5 
"myhost " "=400x5+100+5 "2 

} 

Clients  whose  name  or  class  is  “XTerm”  will  have  an  entry  created  in  the 
“XTerm”  icon  manager.  Clients  whose  name  was  “myhost”  would  be  put 
into  the  “myhost”  icon  manager. 

IconManagerShow  { win_list  } 

Specifies  a list  of  windows  that  should  appear  in  the  icon  manager.  When 
used  in  conjunction  with  the  IconManagerDontShow  variable,  only  the 
windows  in  this  list  will  be  shown  in  the  icon  manager. 

IconRegion  geomstring  vgrav  hgrav  gridwidth  gridheight 

Specifies  an  area  on  the  root  window  in  which  icons  are  placed  if  no  specific 
icon  location  is  provided  by  the  client.  The  geomstring  is  a quoted  string 
containing  a standard  geometry  specification.  If  more  than  one  Icon- 
Region  lines  are  given,  icons  will  be  put  into  the  succeeding  icon  regions 
when  the  first  is  full.  The  vgrav  argument  should  be  either  North  or 
South  and  control  and  is  used  to  control  whether  icons  are  first  filled  in  from 
the  top  or  bottom  of  the  icon  region.  Similarly,  the  hgrav  argument  should 
be  either  East  or  West  and  is  used  to  control  whether  icons  should  be  filled 
in  from  left  from  the  right.  Icons  are  laid  out  within  the  region  in  a grid  with 
cells  gridwidth  pixels  wide  and  gridheight  pixels  high. 

Icons  { win_list  } 

Specifies  a list  of  window  names  and  the  bitmap  filenames  that  should  be 
used  as  their  icons.  For  example: 

Icons 

{ 

"XTerm"  "xterm.icon" 

"xfd"  "xfd_icon" 

} 

Windows  that  match  “XTerm”  and  would  not  be  iconified  by  unmapping, 
and  would  try  to  use  the  icon  bitmap  in  the  file  “xterm.icon”.  If  Force- 
Icons  is  specified,  this  bitmap  will  be  used  even  if  the  client  has  requested 
its  own  icon  pixmap. 

InterpolateMenuColors 

Indicates  that  menu  entry  colors  should  be  interpolated  between  entry  speci- 
fied colors.  In  the  example  below: 

Menu  "mymenu" 

{ 

"Title"  ("black" : "red")  f. title 
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entryl" 

f . nop 

entry2" 

f . nop 

entry3" 

( "white" : "green") 

f . nop 

entry4 " 

f .nop 

entry5" 

("red" : "white") 

f . nop 

The  foreground  colors  for  “entry  1”  and  “entry2”  will  be  interpolated 
between  black  and  white,  and  the  background  colors  between  red  and  green. 
Similarly,  the  foreground  for  “entry4”  will  be  half-way  between  white  and 
red,  and  the  background  will  be  half-way  between  green  and  white. 

MakeTitle  { win_list  } 

Specifies  a list  of  windows  on  which  a titlebar  should  be  placed  and  is  used  to 
request  titles  on  specific  windows  when  WNoTitle  has  been  set. 

MaxWindowSize  string 

Specifies  a geometry  in  which  the  width  and  height  give  the  maximum  size 
for  a given  window.  This  is  typically  used  to  restrict  windows  to  the  size  of 
the  screen.  The  default  is  30000x30000. 

MenuBackground  string 

Specifies  the  background  color  used  for  menus,  and  can  only  be  specified 
inside  of  a Color  or  Monochrome  list.  The  default  is  white. 

MenuFont  string 

Specifies  the  font  to  use  when  displaying  menus.  The  default  is  8x13. 
MenuForeground  string 

Specifies  the  foreground  color  used  for  menus,  and  can  only  be  specified 
inside  of  a Color  or  Monochrome  list.  The  default  is  black. 

MenuShadowColor  string 

Specifies  the  color  of  the  shadow  behind  pull-down  menus  and  can  only  be 
specified  inside  of  a Color  or  Monochrome  list.  The  default  is  black. 

MenuTitleBackground  string 

Specifies  the  background  color  for  f . title  entries  in  menus,  and  can  only 
be  specified  inside  of  a Color  or  Monochrome  list.  The  default  is  white. 

MenuTit leForeground  string 

Specifies  the  foreground  color  for  f . title  entries  in  menus  and  can  only  be 
specified  inside  of  a Color  or  Monochrome  list.  The  default  is  black. 

Monochrome  { colors  } 

Specifies  a list  of  color  assignments  that  should  be  made  if  the  screen  has  a 
depth  of  1.  See  the  description  of  Colors. 

MoveDelta  pixels 

Specifies  the  number  of  pixels  the  pointer  must  move  before  the  f.move  func- 
tion starts  working.  Also  see  the  f .deltastop  function.  The  default  is 
zero  pixels. 
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NoBackingStore 

Indicates  that  twm's  menus  should  not  request  backing  store  to  minimize 
repainting  of  menus.  This  is  typically  used  with  servers  that  can  repaint  fas- 
ter than  they  can  handle  backing  store. 

NoCaseSensitive 

Indicates  that  case  should  be  ignored  when  sorting  icon  names  in  an  icon 
manager.  This  option  is  typically  used  with  applications  that  capitalize  the 
first  letter  of  their  icon  name. 

NoDefaults  Indicates  that  twm  should  not  supply  the  default  titlebuttons  and  bindings. 

This  option  should  only  be  used  if  the  startup  file  contains  a completely  new 
set  of  bindings  and  definitions. 

NoGrabServer 

Indicates  that  twm  should  not  grab  the  server  when  popping  up  menus  and 
moving  opaque  windows. 

NoHighlight  [{  win_list  }] 

Indicates  that  borders  should  not  be  highlighted  to  track  the  location  of  the 
pointer.  If  the  optional  win_list  is  given,  highlighting  will  only  be  dis- 
abled for  those  windows.  When  the  border  is  highlighted,  it  will  be  drawn  in 
the  current  BorderColor.  When  the  border  is  not  highlighted,  it  will  be 
stippled  with  an  gray  pattern  using  the  current  BorderTileForeground 
and  BorderTileBackground  colors. 

NoIconManagers 

Indicates  that  no  icon  manager  should  be  created. 

NoMenuShadows 

Indicates  that  menus  should  not  have  drop  shadows  drawn  behind  them.  This 
is  typically  used  with  slower  servers  since  it  speeds  up  menu  drawing  at  the 
expense  of  making  the  menu  slightly  harder  to  read. 

NoRaiseOnDeiconify 

Indicates  that  windows  that  are  deiconified  should  not  be  raised. 

NoRaiseOnMove 

Indicates  that  windows  should  not  be  raised  when  moved.  This  is  typically 
used  to  allow  windows  to  slide  underneath  each  other. 

NoRaiseOnResize 

Indicates  that  windows  should  not  be  raised  when  resized.  This  is  typically 
used  to  allow  windows  to  be  resized  underneath  each  other. 

NoRaiseOnWarp 

Indicates  that  windows  should  not  be  raised  when  the  pointer  is  warped  into 
them  with  the  f .warpto  function.  If  this  option  is  set,  warping  to  an 
occluded  window  may  result  in  the  pointer  ending  up  in  the  occluding  win- 
dow instead  the  desired  window  (which  causes  unexpected  behavior  with 
f . warpring). 
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NoSaveUnders 

Indicates  that  menus  should  not  request  save-unders  to  minimize  window 
repainting  following  menu  selection.  It  is  typically  used  with  displays  that 
can  repaint  faster  than  they  can  handle  save-unders. 

NoTitle  [{  win_list  }] 

Indicates  that  windows  should  not  have  titlebars.  If  the  optional  win_list 
is  given,  only  those  windows  will  not  have  titlebars.  MakeTitle  may  be 
used  with  this  option  to  force  titlebars  to  be  put  on  specific  windows. 

NoTitleFocus 

Indicates  that  hvm  should  not  set  keyboard  input  focus  to  each  window  as  it  is 
entered.  Normally,  twm  sets  the  focus  so  that  focus  and  key  events  from  the 
titlebar  and  icon  managers  are  delivered  to  the  application.  If  the  pointer  is 
moved  quickly  and  twm  is  slow  to  respond,  input  can  be  directed  to  the  old 
window  instead  of  the  new.  This  option  is  typically  used  to  prevent  this 
“input  lag”  and  to  work  around  bugs  in  older  applications  that  have  prob- 
lems with  focus  events. 

NoTitleHighlight  [{  win_list  }] 

Indicates  that  the  highlight  area  of  the  titlebar,  which  is  used  to  indicate  the 
window  that  currently  has  the  input  focus,  should  not  be  displayed.  If  the 
optional  win_list  is  given,  only  those  windows  will  not  have  highlight 
areas.  This  and  the  SqueezeTitle  options  can  be  set  to  substantially 
reduce  the  amount  of  screen  space  required  by  titlebars. 

OpaqueMove  Indicates  that  the  f .move  function  should  actually  move  the  window  instead 
of  just  an  outline  so  that  the  user  can  immediately  see  what  the  window  will 
look  like  in  the  new  position.  This  option  is  typically  used  on  fast  displays 
(particularly  if  NoGrabServer  is  set). 

Pixmaps  { pixmaps  } 

Specifies  a list  of  pixmaps  that  define  the  appearance  of  various  images.  Each 
entry  is  a keyword  indicating  the  pixmap  to  set,  followed  by  a string  giving 
the  name  of  the  bitmap  file.  The  following  pixmaps  may  be  specified: 

Pixmaps 

{ 

TitleHighlight  "grayl" 

} 

The  default  for  TitleHighlight  is  to  use  an  even  stipple  pattern. 
RandomPlacement 

Indicates  that  windows  with  no  specified  geometry  should  should  be  placed  in 
a pseudo-random  location  instead  of  having  the  user  drag  out  an  outline. 

ResizeFont  string 

Specifies  the  font  to  be  used  for  in  the  dimensions  window  when  resizing 
windows.  The  default  is  fixed. 
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RestartPreviousState 

Indicates  that  twm  should  attempt  to  use  the  WM_STATE  property  on  client 
windows  to  tell  which  windows  should  be  iconified  and  which  should  be  left 
visible.  This  is  typically  used  to  make  try  to  regenerate  the  state  that  the 
screen  was  in  before  the  previous  window  manager  was  shutdown. 

ShowIconManager 

Indicates  that  the  icon  manager  window  should  be  displayed  when  twm  is 
started.  It  can  always  be  brought  up  using  the  f . showiconmgr  function. 

Sort IconManager 

Indicates  that  entries  in  the  icon  manager  should  be  sorted  alphabetically 
rather  than  by  simply  appending  new  windows  to  the  end. 

SqueezeTitle  [{  squeeze_list  }] 

Indicates  that  twm  should  attempt  to  use  the  SHAPE  extension  to  make 
titlebars  occupy  only  as  much  screen  space  as  they  need,  rather  than  extend- 
ing all  the  way  across  the  top  of  the  window.  The  optional  squeeze_list 
may  be  used  to  control  the  location  of  the  squeezed  titlebar  along  the  top  of 
the  window.  It  contains  entries  of  the  form: 

"name"  justification  num  denom 

where  name  is  a window  name,  justification  is  either  left,  center, 
or  right,  and  num  and  denom  are  numbers  specifying  a ratio  giving  the  rel- 
ative position  about  which  the  titlebar  is  justified.  The  ratio  is  measured  from 
left  to  right  if  the  numerator  is  positive,  and  right  to  left  if  negative.  A 
denominator  of  0 indicates  that  the  numerator  should  be  measured  in  pixels. 
For  convenience,  the  ratio  0/0  is  the  same  as  1/2  for  center  and  -1/1  for 
right.  For  example: 

SqueezeTitle 

{ 


XTerm" 

left 

0 

0 

xterml " 

left 

1 

3 

xterm2" 

left 

2 

3 

oclock" 

center 

00 

emacs" 

right 

00 

The  Dont SqueezeTitle  list  can  be  used  to  turn  off  squeezing  on  certain 
titles. 

Startlconif  ied  [{  win_list  }] 

Indicates  that  client  windows  should  initially  be  left  as  icons  until  explicitly 
deiconified  by  the  user.  If  the  optional  win_list  is  given,  only  those  win- 
dows will  be  started  iconic.  This  is  useful  for  programs  that  do  not  support  an 
-iconic  command  line  option  or  resource. 

TitleBackground  string  [{  win_list  }] 

Specifies  the  background  color  used  in  titlebars,  and  may  only  be  specified 
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inside  of  a Color  or  Monochrome  list.  The  optional  win  list  is  a list  of 
window  names  and  colors  so  that  per-window  colors  may  be  specified.  The 
default  is  white. 

TitleButtonBorderWidth  pixels 

Specifies  the  width  in  pixels  of  the  border  surrounding  titlebuttons.  This  is 
typically  set  to  0 to  allow  titlebuttons  to  take  up  as  much  space  as  possible 
and  to  not  have  a border.  The  default  is  1. 

TitleFont  string 

Specifies  the  font  to  used  for  displaying  window  names  in  titlebars.  The 
default  is  8x13. 

TitleForeground  string  [{  win_list  }] 

Specifies  the  foreground  color  used  in  titlebars,  and  may  only  be  specified 
inside  of  a Color  or  Monochrome  list.  The  optional  win_list  is  a list  of 
window  names  and  colors  so  that  per-window  colors  may  be  specified.  The 
default  is  black. 

TitlePadding  pixels 

Specifies  the  distance  between  the  various  buttons,  text,  and  highlight  areas  in 
the  titlebar.  The  default  is  8 pixels. 

Unknownlcon  string 

Specifies  the  filename  of  a bitmap  file  to  be  used  as  the  default  icon.  This  bit- 
map will  be  used  as  the  icon  of  all  clients  which  do  not  provide  an  icon  bit- 
map and  are  not  listed  in  the  Icons  list. 

UsePPosition  string 

Specifies  whether  or  not  twm  should  honor  program -requested  locations 
(given  by  the  PPosition  flag  in  the  WM_NORMAL_HINTS  property)  in 
the  absence  of  a user- specified  position.  The  argument  string  may  have 
one  of  three  values:  off  (the  default)  indicating  that  twm  should  ignore  the 
program-supplied  position,  on  indicating  that  the  position  should  be  used, 
and  non- zero  indicating  that  the  position  should  used  if  it  is  other  than 
(0,0).  The  latter  option  is  for  working  around  a bug  in  older  toolkits. 

WarpCursor  [{  win_list  )] 

Indicates  that  the  pointer  should  be  warped  into  windows  when  they  are 
deiconified.  If  the  optional  win_list  is  given,  the  pointer  will  only  be 
warped  when  those  windows  are  deiconified. 

WindowRing  { win_list  } 

Specifies  a list  of  windows  along  which  the  f . warpring  function  cycles. 

Wa  rpUnmapped 

Indicates  that  that  the  f .warpto  function  should  deiconify  any  iconified 
windows  it  encounters.  This  is  typically  used  to  make  a key  binding  that  will 
pop  a particular  window  (such  as  xmh),  no  matter  where  it  is.  The  default  is 
for  f . warpto  to  ignore  iconified  windows. 
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XorValue  number 

Specifies  the  value  to  use  when  drawing  window  outlines  for  moving  and 
resizing.  This  should  be  set  to  a value  that  will  result  in  a variety  of  of  distin- 
guishable colors  when  exclusive-or’ed  with  the  contents  of  the  user’s  typical 
screen.  Setting  this  variable  to  1 often  gives  nice  results  if  adjacent  colors  in 
the  default  colormap  are  distinct.  By  default,  twm  will  attempt  to  cause  tem- 
porary lines  to  appear  at  the  opposite  end  of  the  colormap  from  the  graphics. 

Zoom  [ count  ] Indicates  that  oudines  suggesting  movement  of  a window  to  and  from  its 
iconified  state  should  be  displayed  whenever  a window  is  iconified  or  deicon- 
ified.  The  optional  count  argument  specifies  the  number  of  outlines  to  be 
drawn.  The  default  count  is  8. 

The  following  variables  must  be  set  after  the  fonts  have  been  assigned,  so  it  is  usually  best  to 
put  them  at  the  end  of  the  variables  or  beginning  of  the  bindings  sections: 

Def aultFunct ion  function 

Specifies  the  function  to  be  executed  when  a key  or  button  event  is  received 
for  which  no  binding  is  provided.  This  is  typically  bound  to  f . nop, 
f . beep,  or  a menu  containing  window  operations. 

WindowFunct ion  function 

Specifies  the  function  to  execute  when  a window  is  selected  from  the  Twm- 
windows  menu.  If  this  variable  is  not  set,  the  window  will  be  deiconified 
and  raised. 


Bindings 

After  the  desired  variables  have  been  set,  functions  may  be  attached  titlebuttons  and  key  and 
pointer  buttons.  Titlebuttons  may  be  added  from  the  left  or  right  side  and  appear  in  the  titlebar 
from  left-to-right  according  to  the  order  in  which  they  are  specified.  Key  and  pointer  button 
bindings  may  be  given  in  any  order. 

Titlebuttons  specifications  must  include  the  name  of  the  pixmap  to  use  in  the  button  box  and 
the  function  to  be  invoked  when  a pointer  button  is  pressed  within  them: 

LeftTitleButton  " bitmapname”=  function 

or: 

RightTitleButton  "bitmapname"=  function 

The  bitmapname  may  refer  to  one  of  the  built-in  bitmaps  (which  are  scaled  to  match 
Tit  leFont)  by  using  the  appropriate  colon-prefixed  name  described  above. 

Key  and  pointer  button  specifications  must  give  the  modifiers  that  must  be  pressed,  over  which 
parts  of  the  screen  the  pointer  must  be,  and  what  function  is  to  be  invoked.  Keys  are  given  as 
strings  containing  the  appropriate  keysym  name;  buttons  are  given  as  the  keywords  But- 
tonl-Button5: 

"FP1"  = modlist  : context  : function 

Buttonl  = modlist  : context  : function 
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The  modlist  is  any  combination  of  the  modifier  names  shift,  control,  and  meta  (which 
may  be  abbreviated  as  s,  c,  and  m respectively)  separated  by  a vertical  bar  ( I ).  Similarly,  the 
context  is  any  combination  of  window,  title,  icon,  root,  frame,  iconmgr,  their  first 
letters  (iconmgr  abbreviation  is  m),  or  all,  separated  by  a vertical  bar.  The  function  is 
any  of  the  f . keywords  described  below.  For  example,  the  default  startup  file  contains  the  fol- 
lowing bindings: 


Buttonl 

= 

: root 

f.menu  "TwmWindows" 

Buttonl 

= 

m 

: window  | 

icon 

f. function  "move-or-lower" 

Button2 

= 

m 

: window  | 

icon 

f . iconif y 

Button3 

= 

m 

: window  | 

icon 

f. function  "move-or-raise" 

Buttonl 

= 

: title 

f. function  "move-or-raise" 

Button2 

= 

: title 

f . raiselower 

Buttonl 

= 

: icon 

f. function  "move-or-iconify 

Button2 

= 

: icon 

f . iconify 

Buttonl 

= 

: iconmgr 

f . iconify 

Button2 

= 

: iconmgr 

f . iconify 

A user  who  wanted  to  be  able  to  manipulate  windows  from  the  keyboard  could  use  the  follow- 
ing bindings: 


FI" 

= 

all 

f . iconify 

F2" 

— 

all 

f . raiselower 

F3" 

= 

all 

f. warpring  "next" 

F4  " 

= 

all 

f.warpto  "xmh" 

F5" 

= 

all 

f.warpto  "emacs" 

F6" 

= 

all 

f.colormap  "next" 

F7" 

= 

all 

f.colormap  "default" 

F20" 

= 

all 

f . warptoscreen  "next 

Left" 

= 

m 

all 

f .backiconmgr 

Right" 

= 

m 

s all 

f . forwiconmgr 

Up" 

= 

m 

all 

f . upiconmgr 

Down" 

= 

m 

s all 

f . downiconmgr 

twm  provides  many  more  window  manipulation  primitives  than  can  be  conveniently  stored  in  a 
titlebar,  menu,  or  set  of  key  bindings.  Although  a small  set  of  defaults  are  supplied  (unless  the 
NoDef  aults  is  specified),  most  users  will  want  to  have  their  most  common  operations  bound 
to  key  and  button  strokes.  To  do  this,  twm  associates  names  with  each  of  the  primitives  and 
provides  user-defined  functions  for  building  higher  level  primitives  and  menus  for  interactively 
selecting  among  groups  of  functions. 

User-defined  functions  contain  the  name  by  which  they  are  referenced  in  calls  to  f .func- 
tion and  a list  of  other  functions  to  execute.  For  example: 

Function  "move-or-lower"  { f.move  f.deltastop  f. lower  } 

Function  "move-or-raise"  { f.move  f.deltastop  f. raise  } 

Function  "move-or-iconify"  { f.move  f.deltastop  f.iconify  } 

Function  "restore-colormap"  { f.colormap  "default"  f. lower  } 

The  function  name  must  be  used  in  f . function  exactly  as  it  appears  in  the  function  specifi- 
cation. 
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In  the  descriptions  below,  if  the  function  is  said  to  operate  on  the  selected  window,  but  is 
invoked  from  a root  menu,  the  cursor  will  be  changed  to  the  Select  cursor  and  the  next  win- 
dow to  receive  a button  press  will  be  chosen: 

! string  This  is  an  abbreviation  for  f . exec  string. 

f.  auto  raise  Toggles  whether  or  not  the  selected  window  is  raised  whenever  entered  by 
the  pointer.  See  the  description  of  the  variable  AutoRaise. 

f .backiconmgr 

Warps  the  pointer  to  the  previous  column  in  the  current  icon  manager,  wrap- 
ping back  to  the  previous  row  if  necessary. 

f . beep  Sounds  the  keyboard  bell. 

f .bottomzoom 

Similar  to  the  f . full  zoom  function,  but  resizes  the  window  to  fill  only  the 
bottom  half  of  the  screen. 


f . circledown 

Lowers  the  top-most  window  that  occludes  another  window, 
f . circleup  Raises  the  bottom-most  window  that  is  occluded  by  another  window. 


f . colormap  string 

Rotates  the  colormaps  (obtained  from  the  WM_COLORMAP_WINDOWS 
property  on  the  window)  that  twm  will  display  when  the  pointer  is  in  this  win- 
dow. The  argument  string  may  have  one  of  the  following  values:  next, 
prev,  and  default. 


f .deiconify  Deiconifies  the  selected  window.  If  the  window  is  not  an  icon,  this  function 
does  nothing. 

f .delete  Sends  the  WM_DELETE_WINDOW  message  to  the  selected  window  if  the 
client  application  has  requested  it  through  the  WM_PROTOCOLS  window 
property.  The  application  is  supposed  to  respond  to  the  message  by  removing 
the  indicated  window.  If  the  window  has  not  requested 
WM_DELETE_WINDOW  messages,  the  keyboard  bell  will  be  rung  indicat- 
ing that  the  user  should  choose  an  alternative  method. 


f .deltastop  Allows  a user-defined  function  to  be  aborted  if  the  pointer  has  been  moved 
more  than  MoveDelta  pixels.  See  the  example  definition  given  for  Func- 
tion "move-or-raise"  at  the  beginning  of  the  section. 


f . destroy  Instructs  the  X server  to  close  the  display  connection  of  the  client  that  created 
the  selected  window.  This  should  only  be  used  as  a last  resort  for  shutting 
down  runaway  clients. 


f . downiconmgr 

Warps  the  pointer  to  the  next  row  in  the  current  icon  manger,  wrapping  to  the 
beginning  of  the  next  column  if  necessary. 
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f . exec  string 

Passes  the  argument  string  to  /bin/sh  for  execution.  In  multiscreen  mode, 
if  string  starts  a new  X client  without  giving  a display  argument,  the  client 
will  appear  on  the  screen  from  which  this  function  was  invoked. 

f . focus  Toggles  the  keyboard  focus  of  the  server  to  the  selected  window,  changing 
the  focus  rule  from  pointer-driven  if  necessary.  If  the  selected  window 
already  was  focused,  this  function  executes  an  f . unfocus. 

f . f orcemove  Like  f .move,  except  that  it  ignores  the  DontMoveOf  f variable, 
f . f orwiconmgr 

Warps  the  pointer  to  the  next  column  in  the  current  icon  manager,  wrapping 
to  the  beginning  of  the  next  row  if  necessary. 

f • full  zoom  Resizes  the  selected  window  to  the  full  size  of  the  display  or  else  restores  the 
original  size  if  the  window  was  already  zoomed. 


f . function  string 

Executes  the  user-defined  function  whose  name  is  specified  by  the  argument 
string. 

f.hbzoom  A synonym  for  f .bottomzoom. 

f . hideiconmgr 

Unmaps  the  current  icon  manager. 

f . horizoom  Similar  to  the  f . zoom  function,  except  that  the  selected  window  is  resized  to 
the  full  width  of  the  display. 

f.htzoom  A synonym  for  f .top  zoom. 

f.hzoom  A synonym  for  f . horizoom. 

f . iconif  y Iconifies  or  deiconifies  the  selected  window  or  icon. 


f .identify  Displays  a summary  of  the  name  and  geometry  of  the  selected  window. 
Clicking  the  pointer  or  pressing  a key  in  the  window  will  dismiss  it. 

f . lef ticonmgr 

Similar  to  f . backiconmgr,  except  that  wrapping  does  not  change  rows. 

f . left  zoom  Similar  to  the  f .bottomzoom  function  but  causes  the  selected  window  is 
only  resized  to  the  left  half  of  the  display. 

f . lower  Lowers  the  selected  window. 


f .menu  string 

Invokes  the  menu  specified  by  the  argument  string.  Cascaded  menus  may 
be  built  by  nesting  calls  to  f . menu. 

f . move  Drags  an  outline  of  the  selected  window  (or  the  window  itself  if  the 

OpaqueMove  variable  is  set)  until  the  invoking  pointer  button  is  released. 
Double  clicking  within  the  number  of  milliseconds  given  by 
ConstrainedMoveTime  warps  the  pointer  to  the  center  of  the  window 
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and  constrains  the  move  to  be  either  horizontal  or  vertical  depending  on 
which  grid  line  is  crossed.  To  abort  a move,  press  another  button  before 
releasing  the  first  button. 

f . nexticonmgr 

Warps  the  pointer  to  the  next  icon  manager  containing  any  windows  on  the 
current  or  any  succeeding  screen. 

f.nop  Does  nothing  and  is  typically  used  with  the  Def aultFunction  or 

WindowFunction  variables  or  to  introduce  blank  lines  in  menus. 

f . previconmgr 

Warps  the  pointer  to  the  previous  icon  manager  containing  any  windows  on 
the  current  or  preceding  screens. 

f . quit  Causes  twm  to  restore  the  window’s  borders  and  exit.  If  twm  is  the  first  client 

invoked  from  xdm,  this  will  result  in  a server  reset. 

f . raise  Raises  the  selected  window. 

f . raiselower 

Raises  the  selected  window  to  the  top  of  the  stacking  order  if  it  is  occluded 
by  any  windows,  otherwise  the  window  will  be  lowered. 

f . ref  resh  Causes  all  windows  to  be  refreshed. 

f .resize  Displays  an  outline  of  the  selected  window.  Crossing  a border  (or  setting 
AutoRelativeResize)  will  cause  the  outline  to  begin  to  rubber  band 
until  the  invoking  button  is  released.  To  abort  a resize,  press  another  button 
before  releasing  the  first  button. 

f.  restart  Kills  and  restarts  twm. 

f . righticonmgr 

Similar  to  f . nexticonmgr,  except  that  wrapping  does  not  change  rows. 

f . right  zoom  Similar  to  the  f .bottomzoom  function,  except  that  the  selected  window  is 
only  resized  to  the  right  half  of  the  display. 

f . saveyourself 

Sends  a WM_SAVE  YOUR  SELF  message  to  the  selected  window  if  it  has 
requested  the  message  in  its  WM_PROTOCOLS  window  property.  Clients 
that  accept  this  message  are  supposed  to  checkpoint  all  state  associated  with 
the  window  and  update  the  WM_COMMAND  property  as  specified  in  the 
ICCCM.  If  the  selected  window  has  not  selected  for  this  message,  the  key- 
board bell  will  be  rung. 

f . showiconmgr 

Maps  the  current  icon  manager. 

f . sorticonmgr 

Sorts  the  entries  in  the  current  icon  manager  alphabetically.  See  the  variable 
SortlconManager. 
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f . source  string 


Assumes  string  is  a file  name.  The  file  is  read  and  parsed  as  a twm  startup 
file.  This  function  is  intended  to  be  used  only  to  re-build  pull-down  menus. 
None  of  the  twm  variables  are  changed. 

f .title 

Provides  a centered,  unselectable  item  in  a menu  definition.  It  should  not  be 
used  in  any  other  context. 

f . topzoom 

Similar  to  the  f .bottomzoom  function,  except  that  the  selected  window  is 
only  resized  to  the  top  half  of  the  display. 

f . twmrc 

Causes  the  startup  customization  file  to  be  re-read.  This  function  is  exactly 
like  the  f . source  function  without  having  to  specify  the  filename. 

f . unfocus 

Resets  the  focus  back  to  pointer-driven.  This  should  be  used  when  a focused 
window  is  no  longer  desired. 

f . upiconmgr 

Warps  the  pointer  to  the  previous  row  in  the  current  icon  manager,  wrapping 
to  the  last  row  in  the  same  column  if  necessary. 

f . version 

Causes  the  twm  version  window  to  be  displayed.  This  window  will  be 
displayed  until  a pointer  button  is  pressed  or  the  pointer  is  moved  from  one 
window  to  another. 

f . vlzoom 

A synonym  for  f . left  zoom. 

f . vrzoom 

A synonym  for  f . right  zoom. 

f . warpring  string 

Warps  the  pointer  to  the  next  or  previous  window  (as  indicated  by  the  argu- 
ment string,  which  may  be  next  or  prev ) specified  in  the  WindowRing 
variable. 


f .warpto  string 

Warps  the  pointer  to  the  window  which  has  a name  or  class  that  matches 
string.  If  the  window  is  iconified,  it  will  be  deiconified  if  the  variable 
WarpUnmapped  is  set  or  else  ignored. 

f . warptoiconmgr  string 

Warps  the  pointer  to  the  icon  manager  entry  associated  with  the  window  con- 
taining the  pointer  in  the  icon  manager  specified  by  the  argument  string. 
If  string  is  empty,  the  current  icon  manager  is  chosen. 

f . warptoscreen  string 

Warps  the  pointer  to  the  screen  specified  by  the  argument  string.  String 
may  be  a number  (e.g.,  0 or  1),  the  word  next  (indicating  the  current  screen 
plus  1,  skipping  over  any  unmanaged  screens),  the  word  back  (indicating  the 
current  screen  minus  1,  skipping  over  any  unmanaged  screens),  or  the  word 
prev  (indicating  the  last  screen  visited). 

f . winref resh 

Similar  to  the  f . ref  resh  function,  except  that  only  the  selected  window  is 
refreshed. 
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f . zoom  Similar  to  the  f . f ullzoom  function,  except  that  the  only  the  height  of  the 

selected  window  is  changed. 

Menus 

Functions  may  be  grouped  and  interactively  selected  using  pop-up  (when  bound  to  a pointer 
button)  or  pull-down  (when  associated  with  a titlebutton)  menus.  Each  menu  specification  con- 
tains the  name  of  the  menu  as  it  will  be  referred  to  by  f .menu,  optional  default  foreground  and 
background  colors,  the  list  of  item  names  and  the  functions  they  should  invoke,  and  optional 
foreground  and  background  colors  for  individual  items: 

Menu  "menuname"  [ ( "def fore" : "defback" ) ] 

{ 

stringl  [ ("forel" : "backn") ] functionl 
string2  [ ("fore2" : "backn") ] function2 


stringN  [ ( "foreN" : "backN" ) ] functionN 

} 

The  menuname  is  case-sensitive.  The  optional  def  fore  and  defback  arguments  specify 
the  foreground  and  background  colors  used  on  a color  display  to  highlight  menu  entries.  The 
string  portion  of  each  menu  entry  will  be  the  text  which  will  appear  in  the  menu.  The 
optional  fore  and  back  arguments  specify  the  foreground  and  background  colors  of  the  menu 
entry  when  the  pointer  is  not  in  the  entry.  These  colors  will  only  be  used  on  a color  display. 
The  default  is  to  use  the  colors  specified  by  the  MenuFo reground  and  MenuBackground 
variables.  The  function  portion  of  the  menu  entry  is  one  of  the  functions,  including  any  user- 
defined  functions,  or  additional  menus. 

There  is  a special  menu  named  TwmWindows  which  contains  the  names  of  all  of  the  client  and 
fwm-supplied  windows.  Selecting  an  entry  will  cause  the  windowFunction  to  be  executed 
on  that  window.  If  WindowFunction  hasn’t  been  set,  the  window  will  be  deiconified  and 
raised. 

Icons 

twm  supports  several  different  ways  of  manipulating  iconified  windows.  The  common  pixmap- 
and-text  style  may  be  laid  out  by  hand  or  automatically  arranged  as  described  by  the  Icon- 
Region  variable.  In  addition,  a terse  grid  of  icon  names,  called  an  icon  manager,  provides  a 
more  efficient  use  of  screen  space  as  well  as  the  ability  to  navigate  among  windows  from  the 
keyboard. 

Neither  client-supplied  icon  windows  nor  dynamic  setting  of  the  icon  pixmap  are  supported 
(icon  name  changes  will  be  updated  automatically). 

An  icon  manager  is  a window  that  contains  names  of  selected  or  all  windows  currently  on  the 
display.  In  addition  to  the  window  name,  a small  button  using  the  default  iconify  symbol  will 
be  displayed  to  the  left  of  the  name  when  the  window  is  iconified.  By  default,  clicking  on  an 
entry  in  the  icon  manager  performs  f . iconify.  To  change  the  actions  taken  in  the  icon  man- 
ager, use  the  the  iconmgr  context  when  specifying  button  and  keyboard  bindings. 
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Moving  the  pointer  into  the  icon  manager  also  directs  keyboard  focus  to  the  indicated  window 
(setting  the  focus  explicitly  or  else  sending  synthetic  events  NoTitleFocus  is  set).  Using 
the  f .upiconmgr,  f . downiconmgr  f . lef ticonmgr,  and  f . righticonmgr  func- 
tions, the  input  focus  can  be  changed  between  windows  directly  from  the  keyboard. 

Bugs 

Lock  and  Mod2  through  Mod5  cannot  be  specified  as  modifier  contexts.  The  correct  fix  is  to 
add  lock,  1,  modi  (for  completeness),  mod2,  mod3,  mod4,  mod5  to  the  parse  and  grammar 
tables,  and  add  a number  as  a valid  key  type  (so  long  as  it  is  1-5). 

The  resource  manager  should  have  been  used  instead  of  all  of  the  window  lists. 

The  IconRegion  variable  should  take  a list. 

Double  clicking  very  fast  to  get  the  constrained  move  function  will  sometimes  cause  the  win- 
dow to  move,  even  though  the  pointer  is  not  moved. 

If  IconifyByUnmapping  is  on  and  windows  are  listed  in  IconManagerDontShow  but 
not  in  Dont  IconifyByUnmapping,  they  may  be  lost  if  they  are  iconified  and  no  bindings 
to  f .menu  TwmWindows  or  f . warpto  are  setup. 

Files 

$HOMEI .twmrc. screen  number 

$HOME/. twmrc 

lusr/lib/Xl  1 /twmlsystem.twmrc 

Environment  Variables 

DISPLAY  This  variable  is  used  to  determine  which  X server  to  use.  It  is  also  set  during 
f . exec  so  that  programs  come  up  on  the  proper  screen. 

HOME  This  variable  is  used  as  the  prefix  for  files  that  begin  with  a tilde  and  for 

locating  the  twm  startup  file. 

See  Also 

X,  Xserver,  xdm,  xrdb 

Copyright 

Portions  copyright  1988  Evans  & Sutherland  Computer  Corporation;  portions  copyright  1989 
Hewlett-Packard  Company  and  the  Massachusetts  Institute  of  Technology.  See  X for  a full 
statement  of  rights  and  permissions. 

Authors 

Tom  LaStrange,  Solboume  Computer; 

Jim  Fulton,  MIT  X Consortium; 

Steve  Pitschke,  Stardent  Computer; 

Keith  Packard,  MIT  X Consortium; 

Dave  Payne,  Apple  Computer. 
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Name 

uwm  - a window  manager  for  X. 

Syntax 

uwm  [options] 

Description 

The  uwm  program  is  a window  manager  client  application  of  the  window  server.  In  releases 
prior  to  4,  uwm  is  the  standard  X window  manager.  As  of  Release  4,  uwm  has  been  moved  to 
the  user-contributed  part  of  the  distribution  and  replaced  in  the  standard  distribution  by  twm. 

When  uwm  is  invoked,  it  searches  a predefined  search  path  to  locate  any  uwm  startup  files.  If 
no  startup  files  exist,  uwm  initializes  its  built-in  defaults. 

If  startup  files  exist  in  any  of  the  following  locations,  it  adds  the  variables  to  the  default  vari- 
ables. In  the  case  of  contention,  the  variables  in  the  last  file  found  override  previous  specifica- 
tions. Files  in  the  uwm  search  path  are: 

lusrllib/Xl  1/uwmJsystem.uwmrc 
$HOME/.uwmrc 

To  use  only  the  settings  defined  in  a single  startup  file,  include  the  variables,  resetbind- 
ings,  resetrnenus,  resetvariables  at  the  top  of  that  specific  startup  file. 

Options 

-f  filename  Names  an  alternate  file  as  a uwm  startup  file. 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  on  which  to  run  the  window 
manager,  host  specifies  the  machine,  server  specifies  the  server  number, 
and  screen  specifies  the  screen  number.  For  example, 

uwm  -display  your_node: 0.1 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 

Startup  File  Variables 

Variables  arc  typically  entered  first,  at  the  top  of  the  startup  file.  By  convention,  resetbind- 
ings,  resetrnenus,  and  resetvariables  head  the  list. 

auto select /noautoselect 

Places  the  menu  cursor  in  first  menu  item.  If  unspecified,  the  menu  cursor  is 
placed  in  the  menu  header  when  the  menu  is  displayed. 

background= col  or 

Specifies  the  default  background  color  for  popup  sizing  windows,  menus,  and 
icons.  The  default  is  to  use  the  WhitePixel  for  the  current  screen. 
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border co lor = color 

Specifies  the  default  border  color  for  popup  sizing  windows,  menus,  and 
icons.  The  default  is  to  use  the  BlackPixel  for  the  current  screen. 
borderwidth=pixels 

Specifies  the  default  width  in  pixels  for  borders  surrounding  icons. 

delta ^pixels 

Indicates  the  number  of  pixels  the  cursor  is  moved  before  the  action  is  inter- 
preted by  the  window  manager  as  a command.  (Also  refer  to  the  delta 
mouse  action.) 

f oreground= col  or 

Specifies  the  default  foreground  color  for  popup  sizing  windows,  menus,  and 
icons.  The  default  is  to  use  the  BlackPixel  for  the  current  screen. 

freeze /no freeze 

Locks  all  other  client  applications  out  of  the  server  during  certain  window 
manager  tasks,  such  as  move  and  resize. 

grid/ nogrid  Displays  a finely-ruled  grid  to  help  you  position  an  icon  or  window  during 
resize  or  move  operations. 

hiconpad =pixels 

Indicates  the  number  of  pixels  to  pad  an  icon  horizontally.  The  default  is  five 
pixels. 

hmenupad =pixels 

Indicates  the  number  of  pixels  to  pad  each  menu  item  to  the  left  and  right  of 
the  text. 

iconf ont=f on tname 

Names  the  font  that  is  displayed  within  icons.  Font  names  for  a given  server 
can  be  obtained  using  xlsfonts. 

maxcolors=n  Limits  the  number  of  colors  the  window  manager  can  use  in  a given  invoca- 
tion. If  set  to  zero,  or  not  specified,  uwm  assumes  no  limit  to  the  number  of 
colors  it  can  take  from  the  color  map.  maxcolors  counts  colors  as  they  are 
included  in  the  file. 

mborderwidth=pixels 

Indicates  the  width  in  pixels  of  the  border  surrounding  menus, 
normali/nonormali 

Places  icons  created  with  f .newiconify  within  the  root  window,  even  if 
they  are  placed  partially  off  the  screen.  With  nonormali  the  icon  is  placed 
exactly  where  the  cursor  leaves  it 

normalw/nonormalw 

Places  window  created  with  f .newiconify  within  the  root  window,  even 
if  they  are  placed  partially  off  the  screen.  With  nonormalw  the  window  is 
placed  exactly  where  the  cursor  leaves  it. 
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push=n  Moves  a window  n number  of  pixels  or  a \/n  times  the  size  of  the  window, 

depending  on  whether  pushabsolute  or  pushrelative  is  specified. 
Use  this  variable  in  conjunction  with  f.  pushup,  f.  pushdown, 
f .pushright,  or  f .pushleft. 

pushabsolute /pushrelative 

pushabsolute  indicates  that  the  number  entered  with  push  is  equivalent  to 
pixels.  When  an  f .push  (left,  right,  up,  or  down)  function  is  called,  the 
window  is  moved  exactly  that  number  of  pixels. 

pushrelative  indicates  that  the  number  entered  with  the  push  variable 
represents  a relative  number.  When  an  f .push  function  is  called,  the  win- 
dow is  invisibly  divided  into  the  number  of  parts  you  entered  with  the  push 
variable,  and  the  window  is  moved  one  part. 

resetbindings,  resetmenus,  resetvariables 

Resets  all  previous  function  bindings,  menus,  and  variables  entries,  specified 
in  any  startup  file  in  the  uwm  search  path,  including  those  in  the  default  envi- 
ronment. By  convention,  these  variables  are  entered  first  in  the  startup  file. 

re s i ze font =fon tname 

Identifies  the  font  of  the  indicator  that  displays  in  the  comer  of  the  window  as 
you  resize  windows.  See  xlsfonts  for  obtaining  font  names. 

resizerelative/noresizerelative 

Indicates  whether  or  not  resize  operations  should  be  done  relative  to  a mov- 
ing edge  or  edges.  By  default,  the  dynamic  rectangle  uses  the  actual  pointer 
location  to  define  the  new  size.  (Available  as  of  Release  3.) 

re verse /no re verse 

Defines  the  display  as  black  characters  on  a white  background  for  the  window 
manager  windows  and  icons. 

viconpad =pixels 

Indicates  the  number  of  pixels  to  pad  an  icon  vertically.  Default  is  five  pix- 
els. 

vmenupad=pixels 

Indicates  the  number  of  pixels  to  pad  each  menu  item  vertically  (i.e.,  above 
and  below  the  text). 

volume=n  Increases  or  decreases  the  base  level  volume  set  by  the  xset(\)  command. 
Enter  an  integer  from  0 to  7, 7 being  the  loudest 

zap/nozap  Causes  ghost  lines  to  follow  the  window  or  icon  from  its  previous  default 
location  to  its  new  location  during  a move  or  resize  operation. 

Binding  Syntax 

function=[control  key  (s)]:[context]:mouse  events:  "menu  name " 

Function  and  mouse  events  are  required  input.  Menu  name  is  required  with  the  f . menu  func- 
tion definition  only. 
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f . beep 

Emits  a beep  from  the  keyboard.  Loudness  is  determined  by  the  volume  vari- 
able. 

f . circledown 

Causes  the  top  window  that  is  obscuring  another  window  to  drop  to  the  bot- 
tom of  the  stack  of  windows. 

f . circleup 

Exposes  the  lowest  window  that  is  obscured  by  other  windows. 

f . continue 

Releases  the  window  server  display  action  after  you  stop  action  with  the 
f .pause  function. 

f . focus 

Directs  all  keyboard  input  to  the  selected  window.  To  reset  the  focus  to  all 
windows,  invoke  f . focus  from  the  root  window. 

f . iconif y 

When  implemented  from  a window,  this  function  converts  the  window  to  its 
respective  icon.  When  implemented  from  an  icon,  f . iconify  converts  the 
icon  to  its  respective  window. 

f .kill 

Kills  the  client  that  created  a window. 

f . lower 

Lowers  a window  that  is  obstructing  a window  below  it. 

f .menu 

Invokes  a menu.  Enclose  ‘menu  name’  in  quotes  if  it  contains  blank  charac- 
ters or  parentheses. 

f . move 

Moves  a window  or  icon  to  a new  location,  which  becomes  the  default  loca- 
tion. 

f .moveopaque 

Moves  a window  or  icon  to  a new  screen  location.  When  using  this  function, 
the  entire  window  or  icon  is  moved  to  the  new  screen  location.  The  grid 
effect  is  not  used  with  this  function. 

f . newiconif y 

Allows  you  to  create  a window  or  icon  and  then  position  the  window  or  icon 
in  a new  default  location  on  the  screen. 

f .pause 

Temporarily  stops  all  display  action.  To  release  the  screen  and  immediately 
update  all  windows,  use  the  f . continue  function. 

f . pushdown 

Moves  a window  down.  The  distance  of  the  push  is  determined  by  the  push 
variables. 

f . pushlef t 

Moves  a window  to  the  left.  The  distance  of  the  push  is  determined  by  the 
push  variables. 

f .pushright 

Moves  a window  to  the  right.  The  distance  of  the  push  is  determined  by  the 
push  variables. 

f .pushup 

Moves  a window  up.  The  distance  of  the  push  is  determined  by  the  push  vari- 
ables. 
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f . raise  Raises  a window  that  is  being  obstructed  by  a window  above  it. 

f .refresh  Results  in  exposure  events  being  sent  to  the  window  server  clients  for  all 

unobscured  or  partially  obscured  windows.  The  windows  will  not  refresh 
correctly  if  the  exposure  events  are  not  handled  properly. 

f .resize  Resizes  an  existing  window.  Note  that  some  clients,  notably  editors,  react 
unpredictably  if  you  resize  the  window  while  the  client  is  running. 

f . restart  Causes  the  window  manager  application  to  restart,  retracing  the  uwm  search 
path  and  initializing  the  variables  it  finds. 


Control  Keys 

By  default,  the  window  manager  uses  meta  as  its  control  key.  It  can  also  use  Ctrl,  shift,  lock,  or 
null  (no  control  key).  Control  keys  must  be  entered  in  lowercase,  and  can  be  abbreviated  as:  c, 
1,  m,  s for  Ctrl,  lock,  meta,  and  shift,  respectively. 

You  can  bind  one,  two,  or  no  control  keys  to  a function.  Use  the  bar  (I ) character  to  combine 
control  keys. 

Note  that  client  applications  other  than  the  window  manager  use  the  shift  as  a control  key.  If 
you  bind  the  shift  key  to  a window  manager  function,  you  can  not  use  other  client  applications 
that  require  this  key. 


Context 

The  context  refers  to  the  screen  location  of  the  pointer  when  a command  is  initiated.  When  you 
include  a context  entry  in  a binding,  the  pointer  must  be  in  that  context  or  the  function  will  not 
be  activated.  The  window  manager  recognizes  the  following  four  contexts:  icon,  window, 
root,  (null). 

The  root  context  refers  to  the  root,  or  background  window,  A (null)  context  is  indicated  when 
the  context  field  is  left  blank,  and  allows  a function  to  be  invoked  from  any  screen  location. 
Combine  contexts  using  the  bar  ( I ) character. 

Mouse  Buttons 

Any  of  the  following  mouse  buttons  are  accepted  in  lowercase  and  can  be  abbreviated  as  1,  m, 
or  r,  respectively:  left,  middle,  right. 

With  the  specific  button,  you  must  identify  the  action  of  that  button.  Mouse  actions  can  be: 

down  Function  occurs  when  the  specified  button  is  pressed  down. 

up  Function  occurs  when  the  specified  button  is  released. 

delta  Indicates  that  the  mouse  must  be  moved  the  number  of  pixels  specified  with 

the  delta  variable  before  the  specified  function  is  invoked.  The  mouse  can  be 
moved  in  any  direction  to  satisfy  the  delta  requirement. 
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Menu  Definition 

After  binding  a set  of  function  keys  and  a menu  name  to  f .menu,  you  must  define  the  menu  to 
be  invoked,  using  the  following  syntax: 

menu  = " menu  name"  { 

" item  name"  : " action " 


} 

Enter  the  menu  name  exactly  the  way  it  is  entered  with  the  f .menu  function  or  the  window 
manager  will  not  recognize  the  link.  If  the  menu  name  contains  blank  strings,  tabs  or  parenthe- 
ses, it  must  be  quoted  here  and  in  the  f .menu  function  entry.  You  can  enter  as  many  menu 
items  as  your  screen  is  long.  You  cannot  scroll  within  menus. 

Any  menu  entry  that  contains  quotes,  special  characters,  parentheses,  tabs,  or  strings  of  blanks 
must  be  enclosed  in  double  quotes.  Follow  the  item  name  by  a colon  (:). 

Menu  Action 

Window  manager  functions 

Any  function  previously  described  (e.g.,  f .move  or  f . iconify). 

Shell  commands  Begin  with  an  exclamation  point  (!)  and  are  set  to  run  in  the  background. 
You  cannot  include  a new  line  character  within  a shell  command. 

Text  strings  Text  strings  are  placed  in  the  window  server’s  cut  buffer. 

Strings  starting  with  an  up  arrow  Q will  have  a new  line  character  appended 
to  the  string  after  the  up  arrow  Q has  been  stripped  from  it. 

Strings  starting  with  a bar  character  (I ) will  be  copied  as  is  after  the  bar  char- 
acter (I ) has  been  stripped. 

Color  Menus 

Use  the  following  syntax  to  add  color  to  menus: 

menu  = " menu  name" (colorl : color2: color3 : color4)  { 

"item  name"  :(color5  :color6)  : "action" 


} 

where: 

col  orl  Foreground  color  of  the  header. 

col  or 2 Background  color  of  the  header. 

color 3 Foreground  color  of  the  highlighter,  the  horizontal  band  of  color  that  moves 

with  the  cursor  within  the  menu. 
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col  or 4 Background  color  of  the  highlighter. 

color 5 Foreground  color  for  the  individual  menu  item. 

color 6 Background  color  for  the  individual  menu  item. 

Color  Defaults 

Colors  default  to  the  colors  of  the  root  window  under  any  of  the  following  conditions: 

If  you  run  out  of  color  map  entries,  either  before  or  during  an  invocation  of  uwm.  If  you  spec- 
ify a foreground  or  background  color  that  does  not  exist  in  the  RGB  color  database  of  the 
server  (see  lusrlliblXlllrgb.txt  for  a sample)  both  the  foreground  and  background  colors  default 
to  the  root  window  colors.  If  you  omit  a foreground  or  background  color,  both  the  foreground 
and  background  colors  default  to  the  root  window  colors.  If  the  total  number  of  colors  speci- 
fied in  the  startup  file  exceeds  the  number  specified  in  the  maxcolors  variable.  If  you  specify 
no  colors  in  the  startup  file. 

Sample  .mwmrc  File 

The  following  sample  startup  file  shows  the  use  of  window  manager  options: 

# Global  variables 

# 

resetbindings; resetvariables; resetmenus 

autoselect 

delta=25 

freeze 

grid 

hiconpad=5 
hmenupad=6 
iconfont=oldeng 
menufont=timroml2b 
resize font =9x1 5 
viconpad=5 
vmenupad=3 
volume=7 
# 

# Mouse  button/key  maps 

# 


#FUNCTION 

KEYS 

CONTEXT 

BUTTON 

MENU (if  any) 

if 

f.menu  = 

meta 

:left  down 

: "WINDOW  OPS" 

f.menu  = 

meta 

: middle  down 

: "EXTENDED  WINDOW  OPS 

f . move  = 

meta 

: w | i 

: right  down 

f.circleup  = 

meta 

: root 

: right  down 

# 


# Menu  specifications 

# 

menu  = "WINDOW  OPS"  { 

" (De) Iconify" : f.iconify 

Move : f . move 
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Resize : 
Lower : 
Raise : 


f . resize 
f . lower 
f . raise 


menu  = "EXTENDED  WINDOW  OPS 
Create  Window: 

Iconify  at  New  Position: 
Focus  Keyboard  on  Window: 
Freeze  All  Windows: 

Unfreeze  All  Windows: 
Circulate  Windows  Up: 
Circulate  Windows  Down: 


! "xterm  &" 
f . lower iconify 
f . focus 
f .pause 
f . continue 
f . circleup 
f . circledown 


Restrictions 

The  color  specifications  have  no  effect  on  a monochrome  system. 

Files 

lusr/liblXl  1 /uwm/system.uwmrc 
$HOME/.uwmrc 

See  Also 

X,  Xserver,  xset,  xlsfonts 

Copyright 

Copyright  1985,  1986,  1987,  1988  Digital  Equipment  Corporation,  Maynard,  MA. 

Author 

M.  Gancarz,  DEC  Ultrix  Engineering  Group,  Merrimack,  New  Hampshire,  using  some  algo- 
rithms originally  by  Bob  Scheifler,  MIT  Laboratory  for  Computer  Science. 
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Name 

xlOtoxl  1 - X version  10  to  version  1 1 protocol  converter. 

Syntax 

xIOtoxll  [options] 

Description 

As  of  Release  4,  this  program  is  no  longer  included  in  the  standard  distribution  of  X. 

xIOtoxll  masquerades  as  an  X Window  System  Version  10  server.  It  enables  an  X Version  10 
client  to  run  unchanged  under  X Version  11  by  converting  Version  10  requests  into  appropriate 
Version  11  requests,  and  by  converting  all  Version  11  events  received  from  the  server  into  Ver- 
sion 10  events.  From  the  perspective  of  Version  10  clients,  all  Version  1 1 clients  look  like  Ver- 
sion 10  clients;  and  from  the  perspective  of  Version  11  clients,  all  Version  10  clients  look  just 
like  Version  11  clients.  Hence,  a Version  11  window  manager  can  manipulate  Version  10 
clients. 

This  program  does  NOT  use  the  X10  libnest  ddX  library.  It  does  actual  protocol  translation, 
rather  than  simply  using  XI 1 graphics  calls  to  implement  X10  low  level  operations.  As  a 
result,  it  is  both  faster  and  more  robust  than  the  X10  Xnest  server. 

Typical  Usage 

The  protocol  converter  must  be  run  after  the  XI 1 server  is  running  and  should  be  run  in  the 
background: 

% xIOtoxll  & 

The  program  will  continue  to  run  until  you  intentionally  kill  it  or  the  XI 1 server  is  shut  down. 

Options 

-display  [host] : server[ . screen] 

Allows  you  to  specify  the  XI 1 display  to  which  you  want  to  be  connected. 
host  specifies  the  machine,  server  specifies  the  server  number,  and 
screen  specifies  the  screen  number.  For  example, 

xIOtoxll  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  of 
the  host  and  screen  elements  to  the  display  specification  can  be  omitted. 
If  host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted, 
screen  0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server 
are  necessary  in  all  cases. 

Note  that  xIOtoxll  will  always  pretend  to  be  an  X10  server  with  the  same 
display  number  as  the  XI 1 server  to  which  it  connects.  For  example,  if  the 
DISPLAY  environment  variable  or  the  -display  option  specifies 
your_node : 1 . 0,  then  xIOtoxll  will  connect  to  the  XI 1 server  on 
your_node  for  display  1 and  then  will  pretend  to  the  the  X10  server  for  dis- 
play 1.  Consequently,  your  X10  clients  will  expect  to  have  the  environment 
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variable  DISPLAY  set  to  your_node  : 1 (but  they  should  still  work  even  if 
your  X10  clients  use  your_node  : 1 . 0). 

Minim\omTileSize=n 

Sets  minimum  acceptable  tile  size  to  n.  There  is  a difference  in  semantics 
between  XIO’s  XQueryShape  and  Xll’s  XQueryBestSize  such  that 
XI 1 will  allow  any  tile  size  but  will  return  the  optimum  whereas  X10 
enforced  a minimum  tile  size.  Usually  this  minimum  tile  size  was  16  and  this 
is  the  default  for  xlOtoxll.  If  you  find  that  this  makes  your  X10  clients  break, 
then  you  can  override  it  with  this  option. 

help  Prints  out  a usage  message  and  exits. 

NoOverrideRedirect 

Instructs  xlOtoxll  to  make  every  effort  not  to  use  OverrideRedirect 
when  creating  and  mapping  windows.  Normally,  xlOtoxll  creates  all  win- 
dows with  the  OverrideRedirect  attribute  set  to  true.  Placing  this 
option  on  the  command  line  will  cause  xlOtoxll  not  to  use  Override- 
Redirect except  for  windows  that  look  like  they  might  be  menus.  This 
will  allow  window  managers  that  provide  titlebars  to  do  so.  Unfortunately,  it 
is  impossible  to  determine  ahead  of  time  what  an  X10  client  intends  to  do 
with  windows.  In  addition,  X10  clients  are  known  to  spontaneously  unmap 
their  windows  which  upsets  XI 1 window  managers  unless  the  Override- 
Redirect attribute  is  true.  Further,  some  XI 1 window  managers  may 
refuse  to  resize  or  move  windows  that  are  marked  with  Override- 
Redirect. This  may  be  fixed  to  some  extent  when  an  Inter  Client  Commu- 
nications Convention  Manual  (ICCCM)  is  adopted  by  the  XI 1 community. 

See  Also 

X,  Xserver 

Bugs 

There  are  limitations  with  respect  to  emulating  Version  10  through  a Version  1 1 server.  See  the 

file  lusr/lib/XIxlOtoxl  1 .help  for  more  details. 

Some  window  managers  may  refuse  to  move,  resize,  or  perform  any  operations  on  X10  client 

windows. 

If  the  source  is  compiled  with  certain  flags,  there  are  significant  debugging  facilities  available. 

Using  the  help  option  will  tell  you  whether  debugging  facilities  are  available.  xlOtoxll 

marks  them  with  OverrideRedirect.  See  “Options”  above. 

Copyright 

Copyright  1988,  Tektronix  Inc. 
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Permission  to  use,  copy,  modify,  and  distribute  this  software  and  its  documentation  for  any  pur- 
pose and  without  fee  is  hereby  granted,  provided  that  the  above  copyright  notice  appear  in  all 
copies  and  that  both  that  copyright  notice  and  this  permission  notice  appear  in  supporting 
documentation. 

Author 

Todd  Brunhoff,  Visual  Systems  Laboratory,  Tektronix. 
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Name 

xauth  - X authority  file  utility 

Syntax 

xauth  [options]  [command  arguments ] 

Description 

Available  as  of  Release  4,  the  xauth  program  is  used  to  edit  and  display  the  authorization  infor- 
mation used  in  connecting  to  the  X server.  This  program  is  usually  to  extract  authorization 
records  from  one  machine  and  merge  them  in  on  another  (as  is  the  case  when  using  remote 
logins  or  to  grant  access  to  other  users).  Commands  (described  below)  may  be  entered  interac- 
tively, on  the  xauth  command  line,  or  in  scripts.  Note  that  this  program  does  not  contact  the  X 
server. 

Options 

The  following  options  may  be  used  with  xauth.  They  may  be  given  individually  (for  example, 
-q  -i)  or  may  combined  (for  example,  -qi): 

-f  authfile  Specifies  the  name  of  the  authority  file  to  use.  By  default,  xauth  will  use  the 
file  specified  by  the  XAUTHORITY  environment  variable  or  Xauthority  in 
the  user’s  home  directory. 

-q  Indicates  that  xauth  should  operate  quietly  and  not  print  unsolicited  status 

messages.  This  is  the  default  if  an  xauth  command  is  is  given  on  the  com- 
mand line  or  if  the  standard  output  is  not  directed  to  a terminal. 

-v  Indicates  that  xauth  should  operate  verbosely  and  print  status  messages  indi- 

cating the  results  of  various  operations  (for  example,  how  many  records  have 
been  read  in  or  written  out).  This  is  the  default  if  xauth  is  reading  commands 
from  its  standard  input  and  its  standard  output  is  directed  to  a terminal. 

-i  Indicates  that  xauth  should  ignore  any  authority  file  locks.  Normally,  xauth 

will  refuse  to  read  or  edit  any  authority  files  that  have  been  locked  by  other 
programs  (usually  xdm  or  another  xauth). 

-b  Indicates  that  xauth  should  attempt  to  break  any  authority  file  locks  before 

proceeding  and  should  only  be  used  to  clean  up  stale  locks. 

Commands 

The  following  commands  may  be  used  to  manipulate  authority  files: 

add  displayname protocolname  hexkey 

An  authorization  entry  for  the  indicated  display  using  the  given  protocol  and 
key  data  is  added  to  the  authorization  file.  The  data  is  specified  as  an  even- 
lengthed  string  of  hexadecimal  digits,  each  pair  representing  one  octet.  The 
first  digit  gives  the  most  significant  4 bits  of  the  octet  and  the  second  digit 
gives  the  least  significant  4 bits.  A protocol  name  consisting  of  just  a single 
period  is  treated  as  an  abbreviation  for  MIT-MAGIC-COOKIE-1 . 
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[n]extract  filename  display  name  . . . 

Authorization  entries  for  each  of  the  specified  displays  are  written  to  the  indi- 
cated file.  If  the  next r act  command  is  used,  the  entries  are  written  in  a 
numeric  format  suitable  for  non-binary  transmission  (such  as  secure  elect- 
ronic mail).  The  extracted  entries  can  be  read  back  in  using  the  merge  and 
nmerge  commands.  If  the  the  filename  consists  of  just  a single  dash,  the 
entries  will  be  written  to  the  standard  output. 

[n]list  [displayname . . . ] 

Authorization  entries  for  each  of  the  specified  displays  (or  all  if  no  displays 
are  named)  are  printed  on  the  standard  output  If  the  nlist  command  is 
used,  entries  will  be  shown  in  the  numeric  format  used  by  the  next r act 
command;  otherwise,  they  are  shown  in  a textual  format.  Key  data  is  always 
displayed  in  the  hexadecimal  format  given  in  the  description  of  the  add  com- 
mand. 

[njmerge  [filename . . . ] 

Authorization  entries  are  read  from  the  specified  files  and  are  merged  into  the 
authorization  database,  superceding  any  matching  existing  entries.  If  the 
nmerge  command  is  used,  the  numeric  format  given  in  the  description  of  the 
extract  command  is  used.  If  a filename  consists  of  just  a single  dash,  the 
standard  input  will  be  read  if  it  hasn’t  been  read  before. 

remove  displayname .. . 

Authorization  entries  matching  the  specified  displays  are  removed  from  the 
authority  file. 

filename 

The  specified  file  is  treated  as  a script  containing  xauth  commands  to  execute. 
Blank  lines  and  lines  beginning  with  a sharp  sign  (#)  are  ignored.  A single 
dash  may  be  used  to  indicate  the  standard  input,  if  it  hasn’t  already  been  read. 

Information  describing  the  authorization  file,  whether  or  not  any  changes 
have  been  made,  and  from  where  xauth  commands  are  being  read  is  printed 
on  the  standard  output. 

If  any  modifications  have  been  made,  the  authority  file  is  written  out  (if 
allowed),  and  the  program  exits.  An  end  of  file  is  treated  as  an  implicit  exit 
command. 

The  program  exits,  ignoring  any  modifications.  This  may  also  be  accom- 
plished by  pressing  the  interrupt  character. 

help  [string] 

A description  of  all  commands  that  begin  with  the  given  string  (or  all  com- 
mands if  no  string  is  given)  is  printed  on  the  standard  output. 


source 


info 


exit 


quit 
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? A short  list  of  the  valid  commands  is  printed  on  the  standard  output 

Display  Names 

Display  names  for  the  add,  [njextract,  [n]list,  [n]merge,  and  remove  commands  use 
the  same  format  as  the  DISPLAY  environment  variable  and  the  common  -display  command 
line  option.  Display-specific  information  (such  as  the  screen  number)  is  unnecessary  and  will 
be  ignored.  Same-machine  connections  (such  as  local-host  sockets,  shared  memory,  and  the 
Internet  Protocol  hostname  localhost ) are  referred  to  as  host- 
name  /unix:  display  number  so  that  local  entries  for  different  machines  may  be  stored  in 
one  authority  file. 

Example 

The  most  common  use  for  xauth  is  to  extract  the  entry  for  the  current  display,  copy  it  to  another 
machine,  and  merge  it  into  the  user’s  authority  file  on  the  remote  machine: 

% xauth  extract  - $DISPLAY  | rsh  other  xauth  merge  - 

Environment  Variables 

This  xauth  program  uses  the  following  environment  variables: 

X AUTHORITY  To  get  the  name  of  the  authority  file  to  use  if  the  -f  option  isn’t  used.  If  this 
variable  is  not  set,  xauth  will  use  Xauthority  in  the  user’s  home  directory. 

HOME  To  get  the  user’s  home  directory  if  XAUTHORITY  isn’t  defined. 

Bugs 

Users  that  have  unsecure  networks  should  take  care  to  use  encrypted  file  transfer  mechanisms 
to  copy  authorization  entries  between  machines.  Similarly,  the  MIT-MAGIC-COOKIE-1  proto- 
col is  not  very  useful  in  unsecure  environments.  Sites  that  are  interested  in  additional  security 
may  need  to  use  encrypted  authorization  mechanisms  such  as  Kerberos. 

Spaces  are  currently  not  allowed  in  the  protocol  name.  Quoting  could  be  added  for  the  truly 
perverse. 

See  Also 

X,  Xserver,  Xau,  xdm 

Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xbiff  - mail  notification  program  for  X. 

Syntax 

xbiff  [options] 


Description 

The  xbiff  program  displays  a little  image  of  a mailbox.  When  there  is  no  mail,  the  flag  on  the 
mailbox  is  down.  When  mail  arrives,  the  flag  goes  up  and  the  mailbox  beeps.  By  default, 
pressing  any  mouse  button  in  the  image  forces  xbiff  to  remember  the  current  size  of  the  mail  file 
as  being  the  “empty”  size  and  to  lower  the  flag. 

This  program  is  nothing  more  than  a wrapper  around  the  Athena  Mailbox  widget. 


Options 

xbiff  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  listed  below: 

-help  Indicates  that  a brief  summary  of  the  allowed  options  should  be  printed  on  the 

standard  error. 


-update  seconds 

Specifies  the  frequency  in  seconds  at  which  xbiff  should  update  its  display.  If 
the  mailbox  is  obscured  and  then  exposed,  it  will  be  updated  immediately. 
The  default  is  60  seconds. 


-file  filename 

Specifies  the  name  of  the  file  which  should  be  monitored.  By  default,  it 
watches  lusrlspoollmaill  username , where  username  is  your  login  name. 

-shape  Indicates  that  the  mailbox  window  should  be  shaped  if  masks  for  the  empty  or 

full  images  are  given.  (Available  as  of  Release  4.) 

-volume  percentage 

Specifies  how  loud  the  bell  should  be  rung  when  new  mail  comes  in. 

The  following  standard  X Toolkit  command  line  arguments  are  commonly  used  with  xbiff : 


-bg 

color 

Specifies  he 

white. 

-bd 

color 

Specifies  the 

-bw 

pixels 

Specifies  the 

-fg 

color 

Specifies  the 

black. 
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-rv  Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 

and  background  colors. 

-geometry  geometry 

Specifies  the  size  and  location  of  the  mailbox  window.  The  -geometry 
option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting 
option  that  begins  with  “g.”  The  argument  to  the  geometry  option  ( geome- 
try) is  referred  to  as  a “standard  geometry  string,”  and  has  the  form 
widthx.height±xoff±yoff.  If  you  do  not  specify  the  geometry,  xbiff 
asks  you  for  window  placement.  See  “Window  Geometry”  in  Chapter  8 of 
this  guide  for  details.  The  default  mailbox  is  48  pixels  on  each  side  and  is 
centered  in  the  window. 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  on  which  to  create  the  mail- 
box window,  host  specifies  which  machine  to  create  the  mailbox  window 
on,  server  specifies  the  server  number,  and  screen  specifies  the  screen 
number.  For  example, 

xbiff  -display  your_node:  0.1 

creates  a mailbox  on  screen  1 of  server  0 on  the  machine  your_node.  If  the 
host  is  omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen 
0 is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 

-xrm  resourcestring 

Specifies  a resource  string  to  be  used.  This  is  especially  useful  for  setting 
resources  that  do  not  have  separate  command  line  options. 

Resources 

This  program  uses  the  Mailbox  widget  in  the  X Toolkit  It  understands  all  of  the  core  resource 
names  and  classes  as  well  as: 

checkCommand  (class  CheckCommand) ) 

Specifies  a shell  command  to  be  executed  to  check  for  new  mail  rather  than 
examining  the  size  of  file.  The  specified  string  value  is  used  as  the  argu- 
ment to  a system( 3)  call  and  may  therefore  contain  I/O  redirection.  An  exit 
status  of  zero  indicates  that  new  mail  is  waiting,  1 indicates  that  there  has 
been  no  change  in  size,  and  2 indicates  that  the  mail  has  been  cleared. 

file  (class  File) 

Specifies  the  name  of  the  file  to  monitor.  The  default  is  to  watch 
lusrlspoollmaill  username , where  username  is  your  login  name. 

flip  (class  Flip) 

Specifies  whether  or  not  the  image  that  is  shown  when  mail  has  arrived 
should  be  inverted.  The  default  is  true.  (Available  as  of  Release  4.) 
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fullPixmap  (class  Pixmap) 

Specifies  a bitmap  to  be  shown  when  new  mail  has  arrived.  (Available  as  of 
Release  4.) 

fullPixmapMask  (class  PixmapMask) 

Specifies  a mask  for  the  bitmap  to  be  shown  when  new  mail  has  arrived. 
(Available  as  of  Release  4.) 

emptyPixmap  (class  Pixmap) 

Specifies  a bitmap  to  be  shown  when  no  new  mail  is  present.  (Available  as  of 
Release  4.) 

emptyPixmapMask  (class  PixmapMask) 

Specifies  a mask  for  the  bitmap  to  be  shown  when  no  new  mail  is  present. 
(Available  as  of  Release  4.) 

width  (class  Width) 

Specifies  the  width  of  the  mailbox. 

height  (class  Height) 

Specifies  the  height  of  the  mailbox. 

onceOnly  (class  Boolean) 

Specifies  that  the  bell  is  only  rung  the  first  time  new  mail  is  found  and  is  not 
rung  again  until  at  least  one  interval  has  passed  with  no  mail  waiting.  The 
window  will  continue  to  indicate  the  presence  of  new  mail  until  it  has  been 
retrieved. 

shapeWindow  (class  ShapeWindow) 

Specifies  whether  or  not  the  mailbox  window  should  be  shaped  to  the  given 
fullPixmapMask  and  emptyPixmapMask.  (Available  as  of  Release  4.) 

update  (class  Interval) 

Specifies  the  frequency  in  seconds  at  which  the  mail  should  be  checked. 

volume  (class  Volume) 

Specifies  how  loud  the  bell  should  be  rung.  The  default  is  33  percent, 
foreground  (class  Foreground) 

Specifies  the  color  for  the  foreground.  The  default  is  black  since  the  core 
default  for  background  is  white. 

reverseVideo  (class  ReverseVideo) 

Specifies  that  the  foreground  and  background  should  be  reversed. 


Actions 

The  Mailbox  widget  provides  the  following  actions  for  use  in  event  translations: 

check  ( ) Causes  the  widget  to  check  for  new  mail  and  display  the  flag  appropriately. 

unset  ( ) Causes  the  widget  to  lower  the  flag  until  new  mail  comes  in. 
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set  ( ) Causes  the  widget  to  raise  the  flag  until  user  resets  it 

The  default  translation  is: 


<ButtonPress> :unset ( ) 


See  Also 

X,  xrdb,  stat(2) 


Author 

Jim  Fulton,  MIT  X Consortium; 

Additional  hacks  by  Ralph  Swick,  DEC/MIT  Project  Athena. 
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Name 

xcalc  - scientific  calculator  for  X. 

Syntax 

xcalc [ options ] 

Description 

xcalc  is  a scientific  calculator  desktop  accessory  that  can  emulate  a TI-30  or  an  HP- IOC.  The 
Release  4 version  of  xcalc  has  been  rewritten  to  use  the  X Toolkit.  Also  as  of  Release  4,  the 
number  in  the  calculator  display  can  be  selected,  allowing  you  to  paste  the  result  of  a calcula- 
tion into  text. 

Versions  of  xcalc  prior  to  Release  4 also  emulate  a slide  rule. 

Options 

xcalc  accepts  all  of  the  standard  X Toolkit  command  line  options,  as  well  as  the  following: 
-stip, -stipple 

Indicates  that  the  background  of  the  calculator  should  be  drawn  using  a 
stipple  of  the  foreground  and  background  colors.  On  monochrome  displays, 
this  improves  the  appearance.  The  -stipple  version  of  this  option  is  avail- 
able as  of  Release  4.  The  -stip  option  can  also  still  be  used. 

-rpn  Indicates  that  Reverse  Polish  Notation  should  be  used.  In  this  mode  the  cal- 

culator will  look  and  behave  like  an  HP- IOC.  Without  this  flag,  it  will  emu- 
late a TI-30. 

-analog  Indicates  that  a slide  rule  should  be  used.  (Eliminated  in  Release  4.) 

The  following  X Toolkit  options  are  commonly  used  with  xcalc : 

-bw  pixels  Specifies  the  border  width  in  pixels. 

-fg  color  Specifies  the  foreground  color  in  use. 

-bg  col  or  Specifies  the  background  color  in  use. 

-rv  Indicates  that  reverse  video  should  be  used. 

-geometry  geometry 

The  xcalc  window  is  created  with  the  specified  size  and  location  determined 
by  the  supplied  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 
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-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  on  which  to  create  the 
xcalc  window,  host  specifies  the  machine  on  which  to  create  the  xcalc  win- 
dow, server  specifies  the  server  number,  and  screen  specifies  the  screen 
number.  For  example, 

xcalc  -display  your_node: 0.1 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 


Calculator  Operations 

Pointer  Usage 

Operations  may  be  performed  with  pointer  button  1 (usually  the  leftmost  button),  or  in  many 
cases,  with  the  keyboard.  Many  common  calculator  operations  have  keyboard  equivalents, 
which  are  called  accelerators,  because  they  facilitate  data  entry.  There  are  several  ways  to 
cause  xcalc  to  exit:  pressing  the  AC  key  of  the  TI  calculator  or  the  ON  key  of  the  HP  calcula- 
tor with  pointer  button  3 (usually  the  rightmost  button);  typing  q,  Q,  or  Ctrl-C  while  the  pointer 
is  in  the  xcalc  window. 

Calculator  Key  Usage  (TI  Mode) 

The  number  keys,  the  +/-  key,  and  the  +,  -,  *,  /,  and  = keys  all  do  exactly  what  you  would  expect 
them  to.  It  should  be  noted  that  the  operators  obey  the  standard  rules  of  precedence.  Thus,  en- 
tering “3+4*5=”  results  in  23,  not  35.  Parentheses  can  be  used  to  override  this.  For  example, 
“ (1+2+3)  * (4+5+6)  =”  is  evaluated  as  “6*15=”  which  results  in  90. 

The  action  associated  with  each  function  are  given  below.  These  are  useful  if  you  are  interest- 
ed in  defining  a custom  calculator.  The  action  used  for  all  digit  keys  is  digit  (n) , where  n is 
the  corresponding  digit,  0-9.  (The  actions  are  available  as  of  Release  4). 


The  keys  are  described  below. 

Mx  Replaces  the  number  in  the  display  with  its  reciprocal.  The  corresponding 

action  is  reciprocal  ( ) . 

x*2  Squares  the  number  in  the  display.  The  corresponding  action  is  square  ( ) . 

SQRT  Evaluates  the  square  root  of  the  number  in  the  display.  The  corresponding  ac- 

tion is  squareRoot  ( ) . 

CE/C  When  pressed  once,  clears  the  number  in  the  display  without  clearing  the 

state  of  the  machine.  Allows  you  to  re-enter  a number  if  you  make  a mistake. 
Pressing  it  twice  clears  the  state  also.  The  corresponding  action  is  clear  ( ) . 

AC  Clears  everything:  the  display,  the  state,  and  the  memory.  Pressing  it  with 

the  third  (usually  the  right)  button  ‘turns  off’  the  calculator,  in  that  it  exits  the 
program.  The  corresponding  action  to  clear  the  state  is  off  () ; to  quit,  the 
action  is  quit  ( ) . 
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Inverts  the  meaning  of  the  function  keys.  See  the  individual  function  keys  for 
details.  The  corresponding  action  is  inverse  ( ) . 

Computes  the  sine  of  the  number  in  the  display,  as  interpreted  by  the  current 
DRG  mode  (see  DRG,  below).  If  inverted,  it  computes  the  arcsine.  The  cor- 
responding action  is  sine  ( ) . 

Computes  the  cosine,  or  arccosine  when  inverted.  The  corresponding  action 
is  cosine  ( ) . 

Computes  the  tangent,  or  arctangent  when  inverted.  The  corresponding  ac- 
tion is  tangent  ( ) . 

Changes  the  DRG  mode,  as  indicated  by  ‘DEG’,  ‘RAD’,  or  ‘GRAD’  at  the 
bottom  of  the  calculator  “liquid  crystal”  display.  When  in  ‘DEG’  mode,  num- 
bers in  the  display  are  taken  as  being  degrees.  In  ‘RAD’  mode,  numbers  are 
in  radians,  and  in  ‘GRAD’  mode,  numbers  are  in  gradians.  When  inverted, 
the  DRG  key  has  the  handy  feature  of  converting  degrees  to  radians  to  gradi- 
ans and  vice-versa.  For  example,  put  the  calculator  into  ‘DEG’  mode,  and 
type  “45  inv  DRG”.  The  calculator  should  display  approximately  .785398, 
which  is  45  degrees  converted  to  radians.  The  corresponding  action  is  de- 
gree () . 

Is  the  constant  ‘e’.  (2.7182818  . . . ) The  corresponding  action  is  e ( ) . 

Is  used  for  entering  exponential  numbers.  For  example,  to  enter  “-2 . 3E-4” 
you  would  type  “2  . 3 +/-  EE  4 The  corresponding  action  is 

scientific ( ) . 

Calculates  the  log  (base  10)  of  the  number  in  the  display.  When  inverted,  it 
raises  10.0  to  the  number  in  the  display.  For  example,  entering  “3  INV 
log”  should  result  in  1000.  The  corresponding  action  is  logarithm  ( ) . 

Calculates  the  log  (base  e)  of  the  number  in  the  display.  When  inverted,  it 
raises  “e”  to  the  number  in  the  display.  For  example,  entering  “e  In”  should 
result  in  1.  The  corresponding  action  is  naturalLog  ( ) . 

Raises  the  number  on  the  left  to  the  power  of  the  number  on  the  right.  For  ex- 
ample, “2  y~x  3 =”  results  in  8,  which  is  2'3.  Also,  “(1+2+3)  y-'x 
(1+2)=”  is  evaluated  as  “6  y~x  3=”  which  results  in  216.  The  corre- 
sponding action  is  power  ( ) . 

The  constant  ’pi’.  (3.1415927 ) The  corresponding  action  is  pi  ( ) . 

Computes  the  factorial  of  the  number  in  the  display.  The  number  in  the  dis- 
play must  be  an  integer  in  the  range  0-500,  though,  depending  on  your  math 
library,  it  might  overflow  long  before  that.  The  corresponding  action  is  fac- 
torial ( ) . 

Left  parenthesis.  The  corresponding  action  for  TI  calculators  is  left- 
Paren ( ) . 
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STO 

RCL 

SUM 

EXC 

+/- 


Calculator  Key  Usage  (RPN  mode) 

The  number  keys,  CHS  (change  sign),  +,  -,  *,  /,  and  ENTR  keys  all  do  exactly  what  you  would 

expect  them  to.  Many  of  the  remaining  keys  are  the  same  as  in  TI  (default)  mode.  The  differ- 
ences are  detailed  below.  The  action  for  the  ENTR  key  is  enter  ( ) . 

<-  Is  a backspace  key  that  can  be  used  while  entering  a number.  It  will  erase  di- 

gits from  the  display.  (See  “Bugs.”)  Inverse  backspace  clears  the  X register. 
The  corresponding  action  is  back  ( ) . 

ON  Clears  everything:  the  display,  the  state,  and  the  memory.  Pressing  it  with 

the  third  (usually  the  right)  pointer  button  ‘turns  off  the  calculator,  in  that  it 
exits  the  program.  The  corresponding  action  to  clear  the  state  is  off  () ; to 
quit,  the  action  is  quit  ( ) . 

INV  Inverts  the  meaning  of  the  function  keys.  This  would  be  the  “f”  key  on  an  HP 

calculator,  but  xcalc  does  not  display  multiple  legends  on  each  key.  See  the 
individual  function  keys  for  details. 

1 0*x  Raises  10.0  to  the  number  in  the  top  of  the  stack.  When  inverted,  it  calculates 

the  log  (base  10)  of  the  number  in  the  display.  The  corresponding  action  is 
tenpower ( ) . 

e‘x  Raises  “e”  to  the  number  in  the  top  of  the  stack.  When  inverted,  it  calculates 

the  log  (base  e)  of  the  number  in  the  display.  The  corresponding  action  is 
epower ( ) . 


Right  parenthesis.  The  corresponding  action  for  TI  calculators  is  right - 
Paren ( ) . 

Division.  The  corresponding  action  is  divide  ( ) . 

Multiplication.  The  corresponding  action  is  multiply  ( ) . 

Subtraction.  The  corresponding  action  is  subtract  ( ) . 

Addition.  The  corresponding  action  is  add  ( ) . 

Perform  calculation.  The  Tl-specific  action  is  equal  ( ) . 

Copies  the  number  in  the  display  to  the  memory  location.  The  corresponding 
action  is  store  () . 

Copies  the  number  from  the  memory  location  to  the  display.  The  correspond- 
ing action  is  recall  ( ) . 

Adds  the  number  in  the  display  to  the  number  in  the  memory  location.  The 
corresponding  action  is  sum  ( ) . 

Swaps  the  number  in  the  display  with  the  number  in  the  memory  location. 
The  corresponding  action  is  exchange  ( ) . 

Negate  (change  sign).  The  corresponding  action  is  negate  ( ) . 

Decimal  point.  The  corresponding  action  is  decimal  ( ) . 
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STO  Copies  the  number  in  the  top  of  the  stack  to  one  of  ten  memory  locations. 

The  desired  memory  is  specified  by  pressing  this  key  and  then  pressing  a digit 
key. 

RCL  Pushes  the  number  from  the  specified  memory  location  onto  the  stack. 

SUM  Adds  the  number  on  top  of  the  stack  to  the  number  in  the  specified  memory 

location. 

x:y  Exchanges  the  numbers  in  the  top  two  stack  positions,  the  X and  Y registers. 

The  corresponding  action  is  XexchangeY  ( ) . 

R v Rolls  the  stack  downward.  When  inverted,  it  rolls  the  stack  upward.  The  cor- 

responding action  is  roll  ( ) . 

Blank  keys  were  used  for  programming  functions  on  the  HP- IOC.  Their  functionality  has  not 
been  duplicated  in  xcalc. 

Keyboard  Equivalents  (Accelerators) 

If  you  have  the  pointer  in  the  xcalc  window,  you  can  use  the  keyboard  to  enter  numbers  and 
other  keys.  Almost  all  of  the  calculator  keys  have  keyboard  equivalents,  which  are  known  as 
accelerators  because  they  speed  entry.  The  number  keys,  the  operator  keys,  and  the  parenthe- 
ses all  have  the  obvious  equivalents.  The  accelerators  defined  by  xcalc  are  listed  in  the  follow- 
ing table: 


TIKey 

HP  Key 

Keyboard 

Accelerator 

TI  Function 

HP  Function 

SQRT 

SQRT 

r 

squareRoot ( ) 

squareRoot ( ) 

AC 

ON 

space 

clear ( ) 

clear ( ) 

AC 

<- 

Delete 

clear ( ) 

back() 

AC 

<- 

Backspace 

clear ( ) 

back ( ) 

AC 

<- 

Control-H 

clear ( ) 

back ( ) 

AC 

Clear 

clear ( ) 

AC 

ON 

q 

quit  () 

quit  ( ) 

AC 

ON 

Control-C 

quit  () 

quit  () 

INV 

i 

i 

inverse ( ) 

inverse ( ) 

sin 

s 

s 

sine ( ) 

sine ( ) 

cos 

c 

c 

cosine ( ) 

cosine ( ) 

tan 

t 

t 

tangent ( ) 

tangent ( ) 

DRG 

DRG 

d 

degree ( ) 

degree ( ) 

e 

e 

e ( ) 

In 

In 

l 

naturalLog ( ) 

naturalLog ( ) 

y~x 

y*x 

power ( ) 

power ( ) 

PI 

PI 

P 

pi  0 

pi  0 

x! 

x! 

I 

factorial ( ) 

factorial ( ) 
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TIKey 

HP  Key 

Keyboard 

Accelerator 

TI  Function 

HP  Function 

( 

( 

leftParen ( ) 

) 

) 

rightParen ( ) 

/ 

/ 

/ 

divide ( ) 

divide ( ) 

* 

★ 

* 

multiply ( ) 

multiply ( ) 

- 

- 

- 

subtract ( ) 

subtract ( ) 

+ 

+ 

+ 

add  ( ) 

add() 

= 

= 

equal ( ) 

0..9 

0..9 

0..9 

digit () 

digit  () 

. 

. 

. 

decimal ( ) 

decimal ( ) 

+/- 

CHS 

n 

negate ( ) 

negate () 

x:y 

X 

XexchangeY ( ) 

ENTR 

Return 

enter ( ) 

ENTR 

Linefeed 

enter ( ) 

Note  that  the  use  of  the  e keyboard  accelerator  to  invoke  the  e calculator  key  is  Release  4 spe- 
cific. In  the  Release  3 version  of  xcalc,  the  e keyboard  accelerator  corresponds  to  the  EE  cal- 
culator key. 

Resources  (Release  4) 

rpn  (class  Rpn) 

Specifies  that  the  rpn  mode  should  be  used.  The  default  is  TI  mode, 
stipple  (class  Stipple) 

Indicates  that  the  background  should  be  stippled.  The  default  is  on  for  monochrome  dis- 
plays, and  off  for  color  displays. 

cursor  (class  Cursor) 

The  name  of  the  symbol  used  to  represent  the  pointer.  The  default  is  hand2. 


Widget  Hierarchy  (Release  4) 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  that  compose 
xcalc.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  the  widget  instance  name. 

XCalc  xcalc 

Form  ti  or  rpn  (the  name  depends  on  the  mode) 

Form  bevel 


Form 


screen 

Label 

M 

Toggle 

LCD 

Label 

INV 

Label 

DEG 

Label 

RAD 

Label 

GRAD 

Label 

P 
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Command 

buttonl 

Command 

button2 

Command 

button3 

and  so  on, ... 

Command 

button38 

Command 

button39 

Command 

button40 

Customization  (Release  4) 

The  application  class  name  is  XCalc. 


As  of  Release  4,  xcalc  has  an  enormous  application  defaults  file,  which  specifies  the  position, 
label,  and  function  of  each  key  on  the  calculator.  It  also  gives  translations  to  serve  as  keyboard 
accelerators.  Because  these  resources  are  not  specified  in  the  source  code,  you  can  create  a 
customized  calculator  by  writing  a private  application  defaults  file,  using  the  Athena  Command 
and  Form  widget  resources  to  specify  the  size  and  position  of  buttons,  the  label  for  each  button, 
and  the  function  of  each  button. 


The  foreground  and  background  colors  of  each  calculator  key  can  be  individually  specified. 
For  the  TI  calculator,  a classical  color  resource  specification  might  be: 


XCalc . ti . Command .background : gray 50 

XCalc . t i . Command . foreground : white 

For  each  of  buttons  20, 25,  30,  35,  and  40,  specify: 

XCalc . ti .button20 . background : black 

XCalc . ti .button20 . foreground : white 

For  each  of  buttons  22, 23, 24, 27, 28, 29,  32,  33,  34,  37, 38,  and  39: 

XCalc . ti .button22 .background : white 

XCalc . ti .button22 . foreground : black 


Resources  (Release  3) 

The  program  uses  the  Xlib  routine  XGetDef  ault(3X)  to  read  defaults,  so  its  resource  names 
are  all  capitalized. 

BorderWidth  Specifies  the  width  of  the  border.  The  default  is  2. 

ReverseVideo 


Indicates  that  reverse  video  should  be  used. 

Stipple  Indicates  that  the  background  should  be  stippled.  The  default  is  on  for  mono- 
chrome displays,  and  off  for  color  displays. 

Mode  Specifies  the  default  mode.  Allowable  values  are  are  rpn,  analog. 

Foreground  Specifies  the  default  color  used  for  borders  and  text. 

Background  Specifies  the  default  color  used  for  the  background. 

NKeyFore, NKeyBack 

Specifies  the  colors  used  for  the  number  keys. 
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OKeyFore, OKeyBack 

Specifies  the  colors  used  for  the  operator  keys. 

FKeyFore, FKeyBack 

Specifies  the  colors  used  for  the  function  keys. 

DispFore, DispBack 

Specifies  the  colors  used  for  the  display. 

IconFore, IconBack 

Specifies  the  colors  used  for  the  icon. 


Customization  (Release  3) 

If  you’re  running  on  a monochrome  display,  you  shouldn’t  need  any  resource  file  entries  for 
xcalc.  However,  xcalc  uses  a lot  of  colors,  given  the  opportunity.  In  the  default  case,  it  will 
just  use  two  colors  (Foreground  and  Background)  for  everything.  This  works  out  nicely. 
However,  if  you’re  a color  fanatic  you  can  specify  the  colors  used  for  the  number  keys,  the  op- 
erator (+,  -,  *,  /,  =)  keys,  the  function  keys,  the  display,  and  the  icon.  On  a color  display,  you 
might  want  to  try  the  following  in  TI  mode: 


xcalc*Foreground : 
xcalc* Background: 
xcalc*NKeyFore : 
xcalc*NKeyBack : 
xcalc*OKeyFore : 
xcalc*OKeyBack : 
xcalc*FKeyFore : 
xcalc*FKeyBack : 
xcalc*DispFore : 
xcalc*DispBack : 
xcalc*IconFore : 
xcalc* IconBack : 


black 

light st eelblue 

black 

white 

aquamarine 

darkslategray 

white 

#900 

yellow 

#777 

red 

white 


Bugs  in  Release  4 

In  HP  mode,  a bug  report  claims  that  the  sequence  of  keys  5,  ENTR,  and  <-  should  clear  the  dis- 
play, but  it  doesn’t. 

Bugs  in  Release  3 

The  calculator  doesn’t  resize. 

The  slide  rule  and  HP  mode  may  or  may  not  work  correctly. 

Base  conversions  are  not  easily  done. 

See  Also 

X,  xrdb,  and  for  Release  4,  the  Athena  Widget  set 

Authors 

John  Bradley,  University  of  Pennsylvania; 

Mark  Rosenstein,  MIT  Project  Athena. 
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X Clipboard  Client — 


\ 


Name 

xclipboard  - X clipboard  client. 

Syntax 

xclipboard  [options] 


Description 

The  xclipboard  program  is  used  to  collect  and  display  text  selections  that  are  sent  to  the  CLIP- 
BOARD by  other  clients.  It  is  typically  used  to  save  CLIPBOARD  selections  for  later  use. 

Since  xclipboard  uses  a Text  Widget  to  display  the  contents  of  the  clipboard,  text  sent  to  the 
CLIPBOARD  may  be  re-selected  for  use  in  other  applications. 

Release  4 Specifics 

The  Release  4 version  of  xclipboard  stores  each  CLIPBOARD  selection  as  a separate  string, 
each  of  which  can  be  selected.  Each  time  CLIPBOARD  is  asserted  by  another  application,  xclip- 
board transfers  the  contents  of  that  selection  to  a new  buffer  and  displays  it  in  the  text  window. 
Buffers  are  never  automatically  deleted,  so  you’ll  want  to  use  the  delete  button  to  get  rid  of 
useless  items. 


xclipboard  also  responds  to  requests  for  the  CLIPBOARD  selection  from  other  clients  by  send- 
ing the  entire  contents  of  the  currently  displayed  buffer. 

An  xclipboard  window  has  the  following  buttons  across  the  top: 


quit 

When  this  button  is  pressed,  xclipboard  exits. 

delete 

When  this  button  is  pressed,  the  current  buffer  is 
displayed. 

new 

Creates  a new  buffer  with  no  contents.  Useful  in 
BOARD  selection  by  hand. 

next 

Displays  the  next  buffer  in  the  list. 

previous 

Displays  the  previous  buffer. 

Release  3 Specifics 

The  Release  3 version  of  xclipboard  has  the  following  buttons  across  the  top: 
quit  When  this  button  is  pressed,  xclipboard  exits. 

erase  When  this  button  is  pressed,  the  contents  of  the  text  window  are  erased.  (The 

erase  button  is  not  functional.) 


Options 

The  x clipboard  program  accepts  all  of  the  standard  X Toolkit  command  line  options  as  well  as 
the  following: 

-w  Indicates  that  lines  of  text  that  are  too  long  to  be  displayed  on  one  line  in  the 

clipboard  should  wrap  around  to  the  following  lines. 

-nw  Indicates  that  long  lines  of  text  should  not  wrap  around.  This  is  the  default 

behavior. 
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Some  of  the  more  common  Toolkit  options  used  with  xclipboard  are: 

-display  [host]:  server[.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  create  the  xclip- 
board windows,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 

xclipboard  -display  your_node: 0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your  node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screep 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  xclipboard  window  is  created  with  the  specified  size  and  location  deter- 
mined by  the  supplied  geometry  specification.  The  -geometry  option  can 
be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that 
begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx.- 
height±xoff±yoff. 

Sending  and  Retrieving  Clipboard  Contents 

Text  is  copied  to  the  clipboard  whenever  a client  asserts  ownership  of  the  CLIPBOARD  selec- 
tion. Text  is  copied  from  the  clipboard  whenever  a client  requests  the  contents  of  the  CLIP- 
BOARD selection.  Examples  of  event  bindings  that  a user  may  wish  to  include  in  a resource 
configuration  file  to  use  the  clipboard  are: 

*VT100 . Translations : #override  \ 

Buttonl  <Btn3Down>:  select-end (CLIPBOARD)  \n\ 

<Btn2Up>:  insert-selection (PRIMARY, CLIPBOARD)  \n\ 


Resources 

This  program  accepts  all  of  the  standard  X Toolkit  resource  names  and  classes  as  well  as: 
wordwrap  (class  Wordwrap) 

Specifies  whether  or  not  lines  of  text  should  wrap  around  to  the  following 
lines.  The  default  is  no.  (Release  3 only.) 


Widgets 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  that  compose 
xclipboard.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget 
class  name  is  given  first,  followed  by  the  widget  instance  name. 

XClipboard  xclipboard 
Form  form 

Command  quit 
Command  delete 
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X Clipboard  Client 


Command 

new 

Command 

next 

Command 

prev 

Text 

text 

Bugs  In  Release  3 

The  erase  button  is  not  functional. 

It  would  be  nice  to  have  a way  of  specifying  the  file  in  which  the  clipboard  contents  are  saved. 

Files 

lusrllib/Xll/app-defaults/XClipboard  Specifies  required  resources  (as  of  Release  4). 

See  Also 

X,  xcutsel,  xterm,  individual  client  documentation  for  how  to  make  a selection  and  send  it  to 
the  CLIPBOARD. 

Author 

Ralph  R.  Swick,  DEC/MIT  Project  Athena; 

Chris  Peterson,  MIT  X Consortium; 

Keith  Packard,  MIT  X Consortium. 
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/ 


Name 

xclock  - continuously  display  the  time  in  either  analog  or  digital  form. 

Syntax 

xclock  [ options ] 

Description 

xclock  continuously  displays  the  time  of  day,  either  in  digital  or  analog  form.  In  digital  form, 
xclock  displays  the  time  using  a 24-hour  clock.  It  also  displays  the  day,  month,  and  year.  In 
analog  form,  xclock  displays  a standard  12-hour  clock  face.  You  can  set  up  more  than  one 
clock  simultaneously. 

The  default  clock  is  an  analog  clock  with  a black  foreground  on  a white  background.  If  you 
want  to  change  the  clock’s  appearance,  type  in  the  appropriate  options.  For  example, 

xclock  -bd  slatobluo  -fg  navybluo  -hi  darkslatagroy  & 

sets  up  a conventional  12-hour  clock  with  a slate  blue  window  border,  navy  blue  tick  marks, 
and  dark  slate  grey  hands. 

By  default,  the  clock  is  positioned  in  the  upper-left  comer  of  your  background  window.  If  you 
are  running  twm,  you  can  place  the  clock  using  the  pointer. 

Options 

xclock  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  listed  below: 

-help  Displays  a brief  summary  of  xclock' s calling  syntax  and  options. 

-analog  Draws  a conventional  12-hour  clock  face  with  tick  marks  for  each  minute  and 
stroke  marks  for  each  hour.  This  is  the  default. 

-digital  or -d 

Displays  the  date  and  time  in  digital  format.  Note  that  -display  must  be 
used  to  specify  a display. 

-chime  Indicates  that  the  clock  should  chime  once  on  the  half  hour  and  twice  on  the 

hour. 

-hd  col  or  Specifies  the  color  of  the  hands  on  an  analog  clock.  The  default  is  black. 

-hi  color  Specifies  the  color  of  the  edges  of  the  hands  on  an  analog  clock.  Only  useful 

on  color  displays.  The  default  is  black. 

-padding  pixels 

Specifies  the  width  in  pixels  of  the  space  between  the  window  border  and  any 
portion  of  the  xclock  display.  The  default  is  10  pixels  in  digital  mode  and  8 
pixels  in  analog  mode. 

-update  seconds 

Specifies  the  frequency  in  seconds  with  which  xclock  updates  its  display.  If 
the  xclock  window  is  obscured  and  then  exposed,  xclock  overrides  this  setting 
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Analog/DIgltal  Clock 


and  redisplays  immediately.  A value  of  less  than  30  seconds  will  enable  a 
second  hand  on  an  analog  clock.  The  default  is  60  seconds. 

The  following  standard  X Toolkit  options  are  commonly  used  with  xclock : 

-bg  col  or  Determines  the  background  color  of  the  window.  The  default  is  white. 

-bd  color  Determines  the  border  color  of  the  window.  The  default  is  black. 

-bw  pixels  Specifies  the  width  in  pixels  of  the  border  around  the  xclock  window.  The 
default  is  2 pixels. 

-fg  color  Determines  the  color  of  the  text  in  digital  mode,  and  the  color  of  the  tick  and 
stroke  marks  in  analog  mode.  The  default  is  black. 

-fn  font  Specifies  the  font  to  be  used  in  digital  mode.  Any  fixed  width  font  may  be 
used.  The  default  is  6x10. 

-rv  Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 

and  background  colors. 

-geometry  geometry 

Sets  xclock  window  size  and  location  according  to  the  geometry  specifica- 
tion. The  -geometry  option  can  be  (and  often  is)  abbreviated  to  -g,  unless 
there  is  a conflicting  option  that  begins  with  “g.”  The  argument  to  the  geom- 
etry option  ( geometry ) is  referred  to  as  a “standard  geometry  string,”  and 
has  the  form  widthxheight±xoff±yoff. 

In  digital  mode,  height  and  width  are  determined  by  the  font  in  use,  unless 
otherwise  specified.  In  analog  mode,  width  and  height  defaults  are  164  pix- 
els, unless  otherwise  specified.  The  default  value  for  any  unspecified  x or  y 
offset  is  -0.  All  values  are  in  pixels.  If  you  do  not  specify  the  geometry, 
xclock  asks  you  for  window  window. 

-display  [host] : serverf . screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  create  the 
xclock  window,  host  specifies  which  machine  to  create  the  xclock  window 
on,  server  specifies  the  server  number  and  screen  specifies  the  screen 
number.  For  example, 

xclock  -display  your_node: 0.1 

creates  an  xclock  display  on  screen  1 on  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  the  screen  0 is  assumed;  the  server  and  colon  (:)  are  neces- 
sary in  all  cases. 

Note  that  -display  cannot  be  abbreviated  to  -d,  which  is  shorthand  for  the 
-digital  option. 

-xrm  resourcestring 

Specifies  a resource  string  to  be  used.  This  is  especially  useful  for  setting 
resources  that  do  not  have  separate  command  line  options. 
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Resources 

xclock  uses  the  Athena  Clock  widget.  It  understands  all  of  the  core  resource  names  and  classes 
as  well  as: 

width  (class  width) 

Specifies  the  width  of  the  clock. 

height  (class  Height) 

Specifies  the  height  of  the  clock. 

update  (class  Interval) 

Specifies  the  frequency  in  seconds  at  which  the  time  should  be  redisplayed, 
background  (class  Background) 

Determines  the  background  color.  The  default  is  white. 

foreground  (class  Foreground) 

Specifies  the  color  for  the  tick  marks  and  stroke  marks.  Using  the  class  speci- 
fies the  color  for  all  things  that  normally  would  appear  in  the  foreground 
color.  The  default  is  black  since  the  core  default  for  background  is  white. 

hands  (class  Foreground) 

Specifies  the  color  of  the  insides  of  the  clock’s  hands.  The  default  is  the 
foreground  color. 

highlight  (class  Foreground) 

Specifies  the  color  used  to  highlight  the  clock’s  hands.  The  default  is  the 
foreground  color. 

analog  (class  Boolean) 

Specifies  whether  or  not  an  analog  clock  should  be  used  instead  of  a digital 
one.  The  default  is  true. 

chime  (class  Boolean) 

Specifies  whether  or  not  a bell  should  be  rung  on  the  hour  and  half  hour.  The 
default  is  false. 

padding  (class  Margin) 

Specifies  the  amount  of  internal  padding  in  pixels  to  be  used.  The  default  is 

8. 

font  (class  Font) 

Specifies  the  font  to  be  used  for  the  digital  clock.  Note  that  variable  width 
fonts  currently  will  not  always  display  correctly. 

reverseVideo  (class  ReverseVideo) 

Specifies  that  the  foreground  and  background  colors  should  be  reversed. 

Widgets  (Release  4) 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  which  compose 
xclock.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  the  widget  instance  name. 
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XClock  xclock 
Clock  clock 


Files 

lusrllib/Xl  1/app-defaults/XClock 

Specifies  default  resources  (as  of  Release  4). 


Bugs 

xclock  believes  the  system  clock. 

When  in  digital  mode,  the  string  should  be  centered  automatically. 
No  way  to  exit  the  program. 

See  Also 

X,  oclock,  xrdb,  time(3C),  Athena  Clock  widget 


Authors 

Tony  Della  Fera  (MIT-Athena,  DEC); 
Dave  Mankins  (MIT-Athena,  BBN); 
Ed  Moy  (UC  Berkeley). 


340 


X Window  System  User's  Guide 


— Cut  Buffer/Selection  Interchange 


xcutsel 


Name 

xcutsel  - interchange  between  cut  buffer  and  selection. 

Syntax 

xcutsel  [ options ] 

Description 

The  xcutsel  program  is  used  to  copy  the  current  selection  into  a cut  buffer  and  to  make  a selec- 
tion that  contains  the  current  contents  of  the  cut  buffer.  It  acts  as  a bridge  between  applications 
that  don’t  support  selections  and  those  that  do. 

By  default,  xcutsel  will  use  the  selection  named  PRIMARY  and  the  cut  buffer  CUT_BUFFERO. 
Either  or  both  of  these  can  be  overridden  by  command  line  arguments  or  by  resources. 

An  xcutsel  window  has  the  following  buttons: 

quit  When  this  button  is  pressed,  xcutsel  exits.  Any  selections, held  by  xcutsel  are 

automatically  released. 

copy  PRIMARY  toO 

When  this  button  is  pressed,  xcutsel  copies  the  current  selection  into  the  cut 
buffer. 

copy  0 to  PRIMARY 

When  this  button  is  pressed,  xcutsel  converts  the  current  contents  of  the  cut 
buffer  into  the  selection. 

The  button  labels  reflect  the  selection  and  cut  buffer  selected  by  command  line  options  or 
through  the  resource  database. 

When  the  copy  0 to  PRIMARY  button  is  activated,  the  button  will  remain  inverted  as  long  as 
xcutsel  remains  the  owner  of  the  selection.  This  serves  to  remind  you  which  client  owns  the 
current  selection.  Note  that  the  value  of  the  selection  remains  constant;  if  the  cut  buffer  is 
changed,  you  must  again  activate  the  copy  button  to  retrieve  the  new  value  when  desired. 

Options 

xcutsel  accepts  all  of  the  standard  X Toolkit  command  line  options  as  well  as  the  following: 
-selection  name 

Specifies  the  name  of  the  selection  to  use.  The  default  is  PRIMARY.  The  only 
supported  abbreviations  for  this  option  are  -select,  -sel  and  -s,  since 
the  standard  Toolkit  option  -select  ionTimeout  has  a similar  name. 

-cutbuf  fer  number 

Specifies  the  cut  buffer  to  use.  The  default  is  cut  buffer  0. 

The  following  X Toolkit  options  are  commonly  used  with  xcutsel : 
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-display  [host] : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  on  which  to  create  the 
xcutsel  window,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 

xcutsel  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  xcutsel  window  is  created  with  the  specified  size  and  location  determined 
by  the  supplied  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  wldthx- 
height+xoff+yoff. 

Resources 

This  program  accepts  all  of  the  standard  X Toolkit  resource  names  and  classes  as  well  as: 
selection  (class  Selection) 

This  resource  specifies  the  name  of  the  selection  to  use.  The  default  is  PRI- 
MARY. 

cutBuf  fer  (class  CutBuf  fer) 

This  resource  specifies  the  number  of  the  cut  buffer  to  use.  The  default  is  0. 


Widget  Names 

The  following  instance  names  may  be  used  when  user  configuration  of  the  labels  in  them  is 
desired: 

sel-cut  (class  Command) 

This  is  the  copy  selection  to  buffer  button. 

cut-sel  (class  Command) 

This  is  the  copy  buffer  to  selection  button. 

quit  (class  Command) 

This  is  the  quit  button. 


Bugs 

There  is  no  way  to  change  the  name  of  the  selection  or  the  number  of  the  cut  buffer  while  the 
program  is  running. 
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See  Also 

X,  xclipboard,  xterm;  Chapter  4 of  this  guide;  text  widget  documentation,  including  Volume 
Four,  X Toolkit  Intrinsics  Programming  Manual 

Author 

Ralph  R.  Swick,  DEC/MIT  Project  Athena. 
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Display  ditroff  Files — 


\ 


Name 

xditview  - display  ditroff  DVI  files. 

Syntax 

xditview  [ options ] 


Description 

The  xditview  program  displays  ditroff  output  on  an  X display.  It  uses  special  font  metrics  that 
match  the  font  set  distributed  with  XI 1 Release  3,  so  it  does  not  require  access  to  the  server 
machine  for  font  loading. 


Options 

xditview  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  listed  below: 

-help  Indicates  that  a brief  summary  of  the  allowed  options  should  be  printed. 

-page  Specifies  the  page  number  of  the  document  to  be  displayed. 

-backingStore  backing_store_type 

Redisplay  of  the  DVI  window  can  take  upto  a second  or  so.  This  option 
causes  the  server  to  save  the  window  contents  so  that  when  it  is  scrolled 
around  the  viewport,  the  window  is  painted  from  contents  saved  in  backing 
store.  backing_store_type  can  be  one  of  Always,  WhenMapped  or 
NotUseful. 


The  following  standard  X Toolkit  command  line  arguments  are  commonly  used  with  xditview : 


-bg  color 
-bd  color 
-bw  pixels 
-fg  color 
-fn  font 


Specifies  the  color  to  use  for  the  window  background.  The  default  is  white. 
Specifies  the  color  to  use  for  the  window  border.  The  default  is  black. 

Specifies  the  width  in  pixels  of  the  window  border. 

Specifies  the  color  to  use  for  displaying  text  The  default  is  black. 

Specifies  the  font  to  be  used  for  displaying  widget  text.  The  default  is 


“fixed”. 


-rv  Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 

and  background  colors. 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  display  the 
xditview  window,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 


xditview  -display  your_node: 0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
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host  is  omiited,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  xditview  window  is  created  with  the  specified  size  and  location  deter- 
mined by  the  supplied  geometry  specification.  The  -geometry  option  can 
be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that 
begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 

-xrm  resourcestring 

Specifies  a resource  string  to  be  used. 


Resources 

This  program  uses  the  Dvi  widget  in  the  X Toolkit  It  understands  all  of  the  core  resource 
names  and  classes  as  well  as: 

width  (class  width) 

Specifies  the  width  of  the  window. 

height  (class  Height ) 

Specifies  the  height  of  the  window. 

foreground  (class  Foreground) 

Specifies  the  default  foreground  color. 

font  (class  Font) 

Specifies  the  font  to  be  used  for  error  messages. 

Using  xditview  with  ditroff 

To  build  a DVI  file  suitable  for  use  with  xditview,  use  the  device  description  in  devX75: 

$ cd  devX75 
$ makedev  DESC 

$ mkdir  /usr/lib/font/devX75 
$ cp  * . out  /usr/lib/font/devX75 
$ ditroff  -TX75  ditroff _input  | xditview 

See  Also 

X,  xrdb,  ditroff(l) 

Bugs 

xditview  can  be  easily  confused  by  attempting  to  display  a DVI  file  constructed  for  the  wrong 
device.  Support  for  pic  is  not  yet  implemented. 
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Name 

xdm  - X display  manager. 

Syntax 

xdm  [options] 

Description 

xdm  manages  a collection  of  X displays,  both  local  and  possibly  remote  — the  emergence  of  X 
terminals  guided  the  design  of  several  parts  of  this  system,  along  with  the  development  of  the  X 
Consortium  standard  XDMCP,  the  X Display  Manager  Control  Protocol  (introduced  in  Release 
4).  It  is  designed  to  provide  services  similar  to  that  provided  by  init,  getty  and  login  on  charac- 
ter terminals:  prompting  for  login/password,  authenticating  the  user  and  running  a “session.” 

A “session”  is  defined  by  the  lifetime  of  a particular  process;  in  the  traditional  character-based 
terminal  world,  it  is  the  user’s  login  shell  process.  In  the  xdm  context,  it  is  an  arbitrary  session 
manager.  This  is  because  in  a windowing  environment,  a user’s  login  shell  process  would  not 
necessarily  have  any  terminal-like  interface  with  which  to  connect. 

Until  real  session  managers  become  widely  available,  the  typical  xdm  substitute  would  be 
either  a window  manager  with  an  exit  option,  or  a terminal  emulator  running  a shell  - with  the 
condition  that  the  lifetime  of  the  terminal  emulator  is  the  lifetime  of  the  shell  process  that  it  is 
running  — thus  degenerating  the  X session  to  an  emulation  of  the  character-based  terminal  ses- 
sion. 

When  the  session  is  terminated,  xdm  resets  the  X server  and  (optionally)  restarts  the  whole  pro- 
cess. 

Because  xdm  provides  the  first  interface  that  users  will  see,  it  is  designed  to  be  simple  to  use 
and  easy  to  customize  to  the  needs  of  a particular  site,  xdm  has  many  options,  most  of  which 
have  reasonable  defaults.  Browse  through  the  various  sections,  picking  and  choosing  the  things 
you  want  to  change.  Pay  particular  attention  to  “The  Xsession  File”,  which  will  describe  how 
to  set  up  the  style  of  session  desired. 

Options 

First,  note  that  all  of  these  options,  except  -conf  ig,  specify  values  that  can  also  be  specified 
in  the  configuration  file  as  resources. 

-config  configuration_file 

Specifies  a resource  file  which  specifies  the  remaining  configuration  parame- 
ters. If  no  file  is  specified  and  the  file  /usr/lib/Xll/xdm/xdm-config  exists, 
xdm  will  use  it. 

-daemon  Specifies  true  as  the  value  for  the  DisplayManager  .daemonMode 

resource.  This  makes  xdm  close  all  file  descriptors,  disassociate  the  control- 
ling terminal  and  put  itself  in  the  background  when  it  first  starts  up  (just  like 
the  host  of  other  daemons).  It  is  the  default  behavior. 

-debug  debug_level 

Specifies  the  numeric  value  for  the  DisplayManager  .debugLevel 
resource.  A non-zero  value  causes  xdm  to  print  piles  of  debugging  state- 
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ments  to  the  terminal;  it  also  disables  the  DisplayManager .daemon- 
Mode  resource,  forcing  xdm  to  run  synchronously.  To  interpret  these  debug- 
ging messages,  a copy  of  the  source  code  for  xdm  is  almost  a necessity.  No 
attempt  has  been  made  to  rationalize  or  standardize  the  output. 

-error  error_log_file 

Specifies  the  value  for  the  DisplayManager  .errorLogFile  resource. 
This  file  contains  errors  from  xdm  as  well  as  anything  written  to  standard 
error  by  the  various  scripts  and  programs  run  during  the  progress  of  the 
session. 

-nodaemon  Specifies  “false”  as  the  value  for  the  DisplayManager  .daemonMode 
resource. 

-resources  resource_file 

Specifies  the  value  for  the  DisplayManager*resources  resource.  This 
file  is  loaded  using  xrdb  to  specify  configuration  parameters  for  the  authenti- 
cation widget. 

-server  server_entry 

Specifies  the  value  for  the  DisplayManager . servers  resource.  (See 
“Resources”  below.) 

-udpPort  port_number 

Specifies  the  value  for  the  DisplayManager . requestPort  resource. 
This  sets  the  port-number  which  XDM  will  monitor  for  XDMCP  requests.  As 
XDMCP  uses  the  registered  well-known  udp  port  177,  this  resource  should 
probably  not  be  changed  except  for  debugging.  (Available  as  of  Release  4.) 

-session  session program 

Specifies  the  value  for  the  DisplayManager*session  resource.  This 
indicates  the  program  to  run  when  the  user  has  logged  in  as  the  session. 
(Available  as  of  Release  4.) 

-xrm  resource_specification 

Allows  an  arbitrary  resource  to  be  specified,  just  as  most  toolkit  applications. 


Resources 

At  many  stages  the  actions  of  xdm  can  be  controlled  through  the  use  of  the  configuration  file, 
which  is  in  the  familiar  X resource  format.  See  Jim  Fulton’s  article  on  resource  files 
( docltutorialslresources.txt ) for  a description  of  the  format.  Some  resources  modify  the  behav- 
ior of  xdm  on  all  displays,  while  others  modify  its  behavior  on  a single  display.  Where  actions 
relate  to  a specific  display,  the  display  name  is  inserted  into  the  resource  name  between 
“DisplayManager”  and  the  final  resource  name  segment.  For  example,  Display- 
Manager  . expo_0  . startup  is  the  name  of  the  resource  that  defines  the  startup  shell  file  on 
the  “expo:0”  display.  Because  the  resource  manager  uses  colons  to  separate  the  name  of  the 
resource  from  its  value  and  dots  to  separate  resource  name  parts,  xdm  substitutes  underscores 
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scores  for  the  dots  and  colons  when  generating  the  resource  name.  (If  you  are  running  Release 
3,  DisplayManager . expo . 0 . startup  is  the  resource.  In  Release  3,  xdm  substitutes 
dots  for  the  colons  when  generating  the  resource  name.) 

DisplayManager . servers 

Specifies  either  a filename  full  of  server  entries,  one  per  line,  or  a single 
server  entry.  Each  entry  indicates  a display  that  should  constantly  be  man- 
aged and  that  is  not  using  XDMCP.  (If  the  resource  value  begins  with  a slash, 
it  is  assumed  to  be  the  name  of  a file  containing  the  list.)  Each  entry  consists 
of  at  least  three  parts:  a display  name,  a display  class  (Release  4 only),  a dis- 
play type,  and  (for  local  servers)  a command  line  to  start  the  server.  (The  pro- 
gram name  should  be  an  absolute  UNIX  pathname,  since  xdm  does  not  search 
through  the  directories  of  the  PATH  environment  variable.)  Foreign  servers 
can  have  a comment  in  place  of  the  command  line.  A typical  entry  for  local 
display  number  0 would  be: 

:0  Digital-QV  local  /usr/bin/Xll/X  :0 

The  display  types  are: 

local  A local  display,  i.e.,  one  that  has  a server  program  to  run 

foreign  A remote  display,  i.e.,  one  that  has  no  server  program  to  run 

If  you’re  running  the  Release  3 version  of  xdm,  the  following  display  types 
are  also  acceptable: 

localTransient  A local  display  that  has  only  one  session  run 
transient  A remote  display  that  has  only  one  session  run 

The  display  name  must  be  something  that  can  be  passed  in  the  -display 
option  to  any  X program.  This  string  is  used  in  the  display-specific  resources 
to  specify  the  particular  display,  so  be  careful  to  match  the  names  (e.g.,  use 
:0  local  /usr/bin/Xll/X  : 0 instead  of  localhost : 0 local 
/usr/bin/Xll/X  : 0 if  your  other  resources  are  specified  as  Display- 
Manager  ,_0  . session). 

The  display  class  portion  can  also  be  used  in  display-specific  resources,  as  the 
class  portion  of  the  resource.  This  is  useful  if  you  have  a large  collection  of 
similar  displays  (perhaps  several  X terminals)  and  would  like  to  set  resources 
for  groups  of  them.  When  using  XDMCP,  the  display  is  required  to  specify 
the  display  class.  Your  X terminal  documentation  should  describe  a reason- 
ably standard  display  class  string  for  your  device. 

DisplayManager . requestPort 

Indicates  the  UDP  port  number  which  xdm  uses  to  listen  for  incoming 
XDMCP  requests.  Unless  you  need  to  debug  the  system,  leave  this  with  its 
default  value  of  177.  (Available  as  of  Release  4.) 
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DisplayManager . errorLogFile 

Error  output  is  normally  directed  at  the  system  console.  To  redirect  it  simply 
set  this  resource  to  any  filename.  A method  to  send  these  messages  to  syslog 
should  be  developed  for  systems  that  support  it;  however  the  wide  variety  of 
“standard”  interfaces  precludes  any  system -independent  implementation. 
This  file  also  contains  any  output  directed  to  standard  error  by  Xstartup , Xses- 
sion,  and  Xreset,  so  it  will  contain  descriptions  of  problems  in  those  scripts  as 
well. 

DisplayManager . debugLevel 

A non-zero  value  specified  for  this  integer  resource  will  enable  reams  of 
debugging  information  to  be  printed.  It  also  disables  daemon  mode  which 
would  redirect  the  information  into  the  bit-bucket.  Specifying  a non-zero 
debug  level  also  allows  non-root  users  to  run  xdm  which  would  normally  not 
be  useful.  (Available  as  of  Release  4.) 

DisplayManager . daemonMode 

Normally,  xdm  attempts  to  make  itself  into  an  unassociated  daemon  process. 
This  is  accomplished  by  forking  and  leaving  the  parent  process  to  exit,  then 
closing  file  descriptors  and  mangling  the  controlling  terminal.  When  attempt- 
ing to  debug  xdm , this  is  quite  bothersome.  Setting  this  resource  to  false  will 
disable  this  feature.  (Available  as  of  Release  4.) 

DisplayManager .pidFile 

The  filename  specified  will  be  created  to  contain  an  ASCII  representation  of 
the  process  ID  of  the  main  xdm  process.  This  is  quite  useful  when  reinitializ- 
ing the  system,  xdm  also  uses  file  locking  to  attempt  to  eliminate  multiple 
daemons  running  on  the  same  machine,  which  would  cause  quite  a bit  of 
havoc.  (Available  as  of  Release  4.) 

DisplayManager . lockPidFile 

Controls  whether  x dm  uses  file  locking  to  keep  multiple  x dm  processes  from 
running  amok.  On  System  V,  this  uses  the  lockf  library  call,  while  on  BSD  it 
uses  flock.  The  default  value  is  true.  (Available  as  of  Release  4.) 

DisplayManager . remoteAuthDir 

This  is  a directory  name  that  xdm  uses  to  temporarily  store  authorization  files 
for  displays  using  XDMCP.  The  default  value  is  lusrlliblXllIxdm.  (Available 
as  of  Release  4.) 

DisplayManager . autoRescan 

This  boolean  controls  whether  xdm  rescans  the  configuration  file  and  servers 
file  after  a session  terminates  and  the  files  have  changed.  By  default  it  is  true. 
You  can  force  xdm  to  reread  these  files  by  sending  a SIGHUP  to  the  main  pro- 
cess. (Available  as  of  Release  4.) 

DisplayManager . removeDoma inname 

When  computing  the  display  name  for  XDMCP  clients,  the  resolver  will  typi- 
cally create  a fully  qualified  host  name  for  the  terminal.  Since  this  is 
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sometimes  confusing,  xdm  will  remove  the  domain  name  portion  of  the  host 
name  if  it  is  the  same  as  the  domain  name  for  the  local  host  when  this  vari- 
able is  set.  By  default  the  value  is  true.  (Available  as  of  Release  4.) 

DisplayManager . keyFile 

XDM- AUTHENTICATION- 1 style  XDMCP  authentication  requires  that  a 
private  key  be  shared  between  xdm  and  the  terminal.  This  resource  specifies 
the  file  containing  those  values.  Each  entry  in  the  file  consists  of  a display 
name  and  the  shared  key.  By  default,  xdm  does  not  include  support  for  XDM- 
AUTHENTICATION-1  as  it  requires  DES  which  is  not  generally  distribut- 
able. (Available  as  of  Release  4.) 

DisplayManager .DISPLAY . resources 

Specifies  the  name  of  the  file  to  be  loaded  by  xrdb  as  the  resource  database 
onto  the  root  window  of  screen  0 of  the  display.  This  resource  database  is 
loaded  just  before  the  authentication  procedure  is  started,  so  it  can  control  the 
appearance  of  the  “login”  window.  See  “Authentication  Widget  Resources”, 
which  describes  the  various  resources  which  are  appropriate  to  place  in  this 
file.  There  is  no  default  value  for  this  resource,  but  the  conventional  name  is 
/usrllib/Xl  1 IxdmIXresources . 

DisplayManager .DISPLAY . xrdb 

Specifies  the  program  used  to  load  the  resources.  By  default,  xdm  uses 
/usrlbin/Xll/xrdb . 

DisplayManager .DISPLAY . cpp 

Specifies  the  name  of  the  C preprocessor  used  by  xrdb.  (Available  as  of 
Release  4.) 

DisplayManager . DISPLAY .startup 

Specifies  a program  which  is  run  (as  root)  after  the  authentication  process 
succeeds.  By  default,  no  program  is  run.  The  conventional  name  for  a file 
used  here  is  Xstartup.  See  ‘The  Xstartup  File”  below. 

DisplayManager .DISPLAY . session 

Specifies  the  session  to  be  executed  (not  running  as  root).  By  default, 
lusrlbinlXll/xterm  is  run.  The  conventional  name  is  Xsession.  See  “The 
Xsession  File”  below. 

DisplayManager . DISPLAY . reset 

Specifies  a program  which  is  run  (as  root)  after  the  session  terminates.  Again, 
by  default  no  program  is  run.  The  conventional  name  is  Xreset.  See  “The 
Xreset  File”  below. 

DisplayManager . DISPLAY . openDelay 

DisplayManager .DISPLAY . openRepeat 

DisplayManager .DISPLAY . openTimeout 

DisplayManager .DISPLAY . startAttempts 

Numeric  resources  control  the  behavior  of  xdm  when  attempting  to  open 
intransigent  servers.  openDelay  is  the  length  of  the  pause  (in  seconds) 
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between  successive  attempts.  openRepeat  is  the  number  of  attempts  to 
make.  openTimeout  is  the  amount  of  time  to  wait  while  actually  attempt- 
ing the  open  (i.e.,  the  maximum  time  spent  in  the  connect  syscall).  start - 
At tempts  (Release  4)  is  the  number  of  times  this  entire  process  is  done 
before  giving  up  on  the  server.  After  openRepeat  attempts  have  been 
made,  or  if  openTimeout  seconds  elapse  in  any  particular  attempt,  xdm  ter- 
minates and  restarts  the  server,  attempting  to  connect  again.  This  process  is 
repeated  startAttempts  times,  at  which  point  the  display  is  declared 
dead  and  disabled.  Although  this  behaviour  may  seem  arbitrary,  it  has  been 
empirically  developed  and  works  quite  well  on  most  systems.  The  default 
values  are  5 for  openDelay,  5 for  openRepeat,  30  for  openTimeout, 
and  4 for  startAttempts. 

DisplayManager .DISPLAY .pinglnterval 

DisplayManager .DISPLAY .pingTimeout 

To  discover  when  remote  displays  disappear,  xdm  occasionally  “pings”  them, 
using  an  X connection  and  sending  XSync  requests,  pinglnterval 
specifies  the  time  (in  minutes)  between  each  ping  attempt,  pingTimeout 
specifies  the  maximum  amount  of  time  (in  minutes)  to  wait  for  the  terminal  to 
respond  to  the  request.  If  the  terminal  does  not  respond,  the  session  is 
declared  dead  and  terminated.  By  default,  both  are  set  to  5 minutes,  xdm  will 
not  ping  local  displays.  Although  it  would  seem  harmless,  it  is  unpleasant 
when  the  workstation  session  is  terminated  as  a result  of  the  server  hanging 
for  NFS  service  and  not  responding  to  the  ping.  (Available  as  of  Release  4.) 

DisplayManager .DISPLAY . terminate Server 

Specifies  whether  the  X server  should  be  terminated  when  a session  termi- 
nates (instead  of  resetting  it).  This  option  can  be  used  when  the  server  tends 
to  grow  without  bound  over  time  in  order  to  limit  the  amount  of  time  the 
server  is  run.  The  default  value  is  false. 

DisplayManager .DISPLAY . userPath 

xdm  sets  the  PATH  environment  variable  for  the  session  to  this  value.  It 
should  be  a colon  separated  list  of  directories,  see  sh(\)  for  a full  description. 
The  default  value  can  be  specified  in  the  X system  configuration  file  with 
Def  UserPath,  frequently  it  is  set  to  :/bin:/usr/bin:/usr/bin/Xl  1 :lusrlucb . 

DisplayManager .DISPLAY . systemPath 

xdm  sets  the  PATH  environment  variable  for  the  startup  and  reset  scripts  to  the 
value  of  this  resource.  The  default  for  this  resource  is  specified  with  the 
Def ault SystemPath  entry  in  the  system  configuration  file,  but  it  is  fre- 
quently letc:lbin:/usr/bin:lusr/bin/Xll  :/usrlucb . Note  the  conspicuous 
absence  of  from  this  entry.  This  is  a good  practise  to  follow  for  root;  it 
avoids  many  common  trojan  horse  system  penetration  schemes. 

DisplayManager .DISPLAY . systemShell 

xdm  sets  the  SHELL  environment  variable  for  the  startup  and  reset  scripts  to 
the  value  of  this  resource.  By  default,  it  is  /bin/sh. 
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DisplayManager .DISPLAY . f ailsaf eClient 

If  the  default  session  fails  to  execute,  xdm  will  fall  back  to  this  program.  This 
program  is  executed  with  no  arguments,  but  executes  using  the  same  environ- 
ment variables  as  the  session  would  have  had.  See  ‘The  Xsession  File” 
below.  By  default,  lusrlbin/XllIxterm  is  used. 

DisplayManager .DISPLAY . grabServer 

DisplayManager .DISPLAY. grabTimeout 

To  eliminate  obvious  security  shortcomings  in  the  X protocol,  xdm  grabs  the 
server  and  keyboard  while  reading  the  name/password.  The  grabServer 
resource  specifies  if  the  server  should  be  held  for  the  duration  of  the 
name/password  reading,  when  FALSE,  the  server  is  ungrabbed  after  the  key- 
board grab  succeeds,  otherwise  the  server  is  grabbed  until  just  before  the 
session  begins.  The  grabTimeout  resource  specifies  the  maximum  time 
xdm  will  wait  for  the  grab  to  succeed.  The  grab  may  fail  if  some  other  client 
has  the  server  grabbed,  or  possibly  if  the  network  latencies  are  very  high. 
This  resource  has  a default  value  of  3 seconds;  you  should  be  cautious  when 
raising  it  as  a user  can  be  spoofed  by  a look-alike  window  on  the  display.  If 
the  grab  fails,  xdm  kills  and  restarts  the  server  (if  possible)  and  session. 
(Available  as  of  Release  4.) 

DisplayManager .DISPLAY. authorize 

DisplayManager .DISPLAY. authName 

authorize  is  a boolean  resource  that  controls  whether  xdm  generates  and 
uses  authorization  for  the  server  connections.  If  authorization  is  used, 
authName  specifies  the  type  to  use.  Currently,  xdm  supports  only  MIT- 
MAGIC-COOKIE- 1 authorization,  XDM- AUTHORIZATION- 1 could  be 
supported  as  well,  but  DES  is  not  generally  distributable.  XDMCP  connec- 
tions specify  which  authorization  types  are  supported  dynamically,  so  auth- 
Name is  ignored  in  this  case.  When  authorize  is  set  for  a display  and 
authorization  is  not  available,  the  user  is  informed  by  having  a different  mes- 
sage displayed  in  the  login  widget.  By  default,  authorize  is  true;  auth- 
Name is  MIT-MAGIC-COOKIE-1.  (Available  as  of  Release  4.) 

DisplayManager .DISPLAY. authFile 

This  file  is  used  to  communicate  the  authorization  data  from  xdm  to  the 
server,  using  the  -auth  server  command  line  option.  It  should  be  kept  in  a 
directory  which  is  not  world-writable  as  it  could  easily  be  removed,  disabling 
the  authorization  mechanism  in  the  server.  (Available  as  of  Release  4.) 

DisplayManager .DISPLAY . resetForAuth 

The  original  implementation  of  authorization  in  the  sample  server  reread  the 
authorization  file  at  server  reset  time,  instead  of  when  checking  the  initial 
connection.  As  xdm  generates  the  authorization  information  just  before  con- 
necting to  the  display,  an  old  server  would  not  get  up-to-date  authorization 
information.  This  resource  causes  xdm  to  send  SIGHUP  to  the  server  after 
setting  up  the  file,  causing  an  additional  server  reset  to  occur,  during  which 
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time  the  new  authorization  information  will  be  read.  (Available  as  of  Release 
4.) 

DisplayManager .DISPLAY . userAuthDir 

When  xdm  is  unable  to  write  to  the  usual  user  authorization  file 
($HOME/ JCauthority),  it  creates  a unique  file  name  in  this  directory  and 
points  the  environment  variable  XAUTHORITY  at  the  created  file.  By 
default  it  uses  Itmp.  (Available  as  of  Release  4.) 

Controlling  The  Server 

x dm  controls  local  servers  using  POSEX  signals.  SIGHUP  is  expected  to  reset  the  server,  closing 
all  client  connections  and  performing  other  clean  up  duties.  SIGTERM  is  expected  to  terminate 
the  server.  If  these  signals  do  not  perform  the  expected  actions,  xdm  will  not  perform  properly. 

To  control  remote  servers  not  using  XDMCP,  xdm  searches  the  window  hierarchy  on  the  display 
and  uses  the  protocol  request  KillClient  in  an  attempt  to  clean  up  the  terminal  for  the  next 
session.  This  may  not  actually  kill  all  of  the  clients,  as  only  those  which  have  created  windows 
will  be  noticed.  XDMCP  provides  a more  sure  mechanism;  when  xdm  closes  its  initial  connec- 
tion, the  session  is  over  and  the  terminal  is  required  to  close  all  other  connections. 

Controlling  xdm 

xdm  responds  to  two  signals:  SIGHUP  and  SIGTERM.  When  sent  a SIGHUP,  xdm  rereads  the  file 
specified  by  the  DisplayManager . servers  resource  and  notices  if  entries  have  been 
added  or  removed.  If  a new  entry  has  been  added,  xdm  starts  a session  on  the  associated  dis- 
play. Entries  that  have  been  removed  are  disabled  immediately,  meaning  that  any  session  in 
progress  will  be  terminated  without  notice,  and  no  new  session  will  be  started. 

When  sent  a SIGTERM,  xdm  terminates  all  sessions  in  progress  and  exits.  This  can  be  used 
when  shutting  down  the  system. 

xdm  attempts  to  mark  the  various  sub-processes  for  pj(l)  by  editing  the  command  line  argu- 
ment list  in  place.  Because  xdm  can’t  allocate  additional  space  for  this  task,  it  is  useful  to  start 
xdm  with  a reasonably  long  command  line  (15  to  20  characters  should  be  enough).  Each  pro- 
cess that  is  servicing  a display  is  marked  -<Display_Name>. 


Authentication  Widget  Resources 

The  authentication  widget  is  an  application  which  reads  a name/password  pair  from  the  key- 
board. As  this  is  a toolkit  client,  nearly  every  imaginable  parameter  can  be  controlled  with  a 
resource.  Resources  for  this  widget  should  be  put  into  the  file  named  by  Display- 
Manager  .DISPLAY.  resources.  All  of  these  have  reasonable  default  values,  so  it  is  not 
necessary  to  specify  any  of  them. 

xlogin . Login .width,  xlogin . Login .height,  xlogin . Login . x, 
xlogin . Login . y 

The  geometry  of  the  login  widget  is  normally  computed  automatically.  If  you 
wish  to  position  it  elsewhere,  specify  each  of  these  resources. 
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xlogin . Login . foreground 

The  color  used  to  display  the  typed-in  user  name. 

xlogin . Login . font 

The  font  used  to  display  the  typed-in  user  name. 

xlogin . Login . greeting 

A string  which  identifies  this  window.  The  default  is  “Welcome  to  the  X 
Window  System”. 

xlogin . Login . unsecureGreeting 

When  X authorization  is  requested  in  the  configuration  file  for  this  display 
and  none  is  in  use,  this  greeting  replaces  the  standard  greeting.  Its  default 
value  is  ‘This  is  an  unsecure  session”.  (Available  as  of  Release  4.) 

xlogin . Login . greetFont 

The  font  used  to  display  the  greeting. 

xlogin . Login . greetColor 

The  color  used  to  display  the  greeting. 

xlogin . Login . namePrompt 

The  string  displayed  to  prompt  for  a user  name,  xrdb  strips  trailing  white 
space  from  resource  values,  so  to  add  spaces  at  the  end  of  the  prompt  (usually 
a nice  thing),  add  spaces  escaped  with  backslashes.  (In  Release  3,  Control- A 
should  work.)  The  default  is  “Login:”. 

xlogin . Login .passwdPrompt 

The  string  displayed  to  prompt  for  a password.  The  default  is  “Pass- 
word:”. 

xlogin . Login . promptFont 

The  font  used  to  display  both  prompts. 

xlogin . Login . promptColor 

The  color  used  to  display  both  prompts. 

xlogin . Login . fail 

A message  which  is  displayed  when  the  authentication  fails.  The  default  is 
“Login  Failed,  please  try  again”. 

xlogin . Login . f ailFont 

The  font  used  to  display  the  failure  message. 

xlogin . Login . f ailColor 

The  color  used  to  display  the  failure  message. 

xlogin . Login . f ailTimeout 

The  time  (in  seconds)  that  the  fail  message  is  displayed.  The  default  is  30 
seconds. 


X Window  System  User's  Guide 


355 


Reference  Pages 


xdm 


(continued) 


X Display  Manager 


xlogin . Login . translations 

This  specifies  the  translations  used  for  the  login  widget  See  Chapter  9,  Set- 
ting Resources,  and  Appendix  G,  Translation  Table  Syntax,  for  more  informa- 
tion on  translations.  The  default  translation  table  for  xdm  is: 


Ctrl<Key>H : 
Ctrl<Key>D : 
Ctrl<Key>B : 

Ct rl<Key>F : 
Ctrl<Key>A: 
Ctrl<Key>E : 
Ctrl<Key>K : 
Ctrl<Key>U : 
Ctrl<Key>X : 

Ct rl<Key>C : 
Ctrl<Key>\\ : 
<Key>BackSpace : 
<Key>Delete : 
<Key>Return : 
<Key> : 

The  actions  that  are  supported  by  the  wl 


delete-previous-character ( ) \n\ 
delete-character ( ) \n\ 

move-backward-character ( ) \n\ 
move-forward-character ()  \n\ 

move-to-begining ( ) \n\ 

move-to-end()  \n\ 
erase-to-end-of-line ( ) \n\ 

erase-line ()  \n\ 
erase-line ()  \n\ 
restart-session ( ) \n\ 

abort-session ( ) \n\ 

delete-previous-character ( ) \n\ 

delete-previous-character ( ) \n\ 

f inish-f ield ( ) \n\ 
insert-char ( ) \ 

L are: 


delete-previous-character 

delete-character 

move-backward-character 

move-forward-character 

move-to-begining 

move-to-end 

erase-to-end-of-line 


Erases  the  character  before  the  cursor. 

Erases  the  character  after  the  cursor. 

Moves  the  cursor  backward. 

Moves  the  cursor  forward. 

(Apologies  about  the  spelling  error.)  Moves  the  cursor  to 
the  beginning  of  the  editable  text 

Moves  the  cursor  to  the  end  of  the  editable  text 

Erases  all  text  after  the  cursor. 


erase-line 


Erases  the  entire  text 


finish-field  If  the  cursor  is  in  the  name  field,  proceeds  to  the  password 

field;  if  the  cursor  is  in  the  password  field,  check  the  current 
name/password  pair.  If  the  name/password  pair  are  valid, 
xdm  starts  the  session.  Otherwise  the  failure  message  is 
displayed  and  the  user  is  prompted  to  try  again. 

abort-session  Terminates  and  restarts  the  server. 


abort-display  Terminates  the  server,  disabling  it.  This  is  a rash  action  and 

is  not  accessible  in  the  default  configuration.  It  can  be  used 
to  stop  x dm  when  shutting  the  system  down,  or  when  using 
xdmshell. 
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restart-session  Resets  the  X server  and  starts  a new  session.  This  can  be 

used  when  the  resources  have  been  changed  and  you  want 
to  test  them,  or  when  the  screen  has  been  overwritten  with 
system  messages. 

insert-char  Inserts  the  character  typed. 

set-session-argument  Specifies  a single  word  argument  which  is  passed  to  the 

session  at  startup.  See  “The  Xsession  File”  and  ‘Typical 
Usage”  below. 

allow-all-access  Disables  access  control  in  the  server,  this  can  be  used  when 

the  Xauthority  file  cannot  be  created  by  xdm.  Be  very 
careful  when  using  this;  it  might  be  better  to  disconnect  the 
machine  from  the  network  first.  (Available  as  of  Release  4.) 


The  Xstartup  File 

This  file  is  typically  a shell  script.  It  is  run  as  “root”  and  should  be  very  careful  about  security. 
This  is  the  place  to  put  commands  which  make  fake  entries  in  /etc/utmp,  mount  users’  home 
directories  from  file  servers,  display  the  message  of  the  day,  or  abort  the  session  if  logins  are 
not  allowed.  Various  environment  variables  are  set  for  the  use  of  this  script: 

DISPLAY  is  set  to  the  associated  display  name. 

HOME  is  set  to  the  home  directory  of  the  user. 

USER  is  set  to  the  user  name. 

PATH  is  set  to  the  value  of  DisplayManager  .DISPLAY . systemPath. 

SHELL  is  set  to  the  value  of  DisplayManager  .DISPLAY . systemShell. 

XAUTHORITY  may  be  set  to  a non-standard  authority  file  (Release  4). 

No  arguments  of  any  kind  are  passed  to  the  script,  xdm  waits  until  this  script  exits  before  start- 
ing the  user  session.  If  the  exit  value  of  this  script  is  non-zero,  xdm  discontinues  the  session 
immediately  and  starts  another  authentication  cycle. 


The  Xsession  File 

This  is  the  script  that  is  run  as  the  user’s  session.  It  is  run  with  the  permissions  of  the  author- 
ized user,  and  has  several  environment  variables  specified: 

DISPLAY  is  set  to  the  associated  display  name. 

HOME  is  set  to  the  home  directory  of  the  user. 

USER  is  set  to  the  user  name. 

PATH  is  set  to  the  value  of  DisplayManager  .DISPLAY . userPath. 

SHELL  is  set  to  the  user’s  default  shell  (from  letc/passwd ). 

XAUTHORITY  may  be  set  to  a non-standard  authority  file  (Release  4). 
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At  most  installations,  Xsession  should  look  in  $HOME  for  a file  jcsession  which  would  contain 
commands  that  each  user  would  like  to  use  as  a session.  This  would  replace  the  system  default 
session.  Xsession  should  also  implement  the  system  default  session  if  no  user-specified  session 
exists.  See  ‘Typical  Usage”  below. 

An  argument  may  be  passed  to  this  program  from  the  authentication  widget  using  the  ‘set- 
session-argument’  action.  This  can  be  used  to  select  different  styles  of  session.  One  very  good 
use  of  this  feature  is  to  allow  the  user  to  escape  from  the  ordinary  session  when  it  fails.  This 
would  allow  users  to  repair  their  own  jcsession  if  it  fails,  without  requiring  administrative  inter- 
vention. The  section  “Typical  Usage”  demonstrates  this  feature. 


The  Xreset  File 

Symmetrical  with  Xstartup,  this  script  is  run  after  the  user  session  has  terminated.  Run  as  root, 
it  should  probably  contain  commands  that  undo  the  effects  of  commands  in  Xstartup , removing 
fake  entries  from  /etc/utmp  or  unmounting  directories  from  file  servers.  The  collection  of  envi- 
ronment variables  that  were  passed  to  Xstartup  are  also  given  to  Xreset. 


Typical  Usage 

Actually,  xdm  is  designed  to  operate  in  such  a wide  variety  of  environments  that  “typical”  is 
probably  a misnomer.  However,  this  section  will  focus  on  making  xdm  a superior  solution  to 
traditional  means  of  starting  X from  letc/ttys  or  manually. 

First  off,  the  xdm  configuration  file  should  be  set  up.  A good  thing  to  do  is  to  make  a directory 
(lusr/lib/Xl  1/xdm  comes  immediately  to  mind)  that  will  contain  all  of  the  relevant  files.  Here  is 
a reasonable  configuration  file  for  Release  4,  which  could  be  named  xdm-config : 


DisplayManager . servers : 
DisplayManager . errorLogFile : 
DisplayManager .pidFile : 
DisplayManager*resources : 
DisplayManager*session : 
DisplayManager ._0 . authorize : 
DisplayManager*authorize : 


/usr/lib/Xll/xdm/Xservers 

/usr/lib/Xll/xdm/xdm-errors 

/usr/lib/Xll/xdm/xdm-pid 

/usr/lib/Xll/xdm/Xresources 

/usr/lib/Xll/xdm/Xsession 

true 

false 


If  you  are  running  the  Release  3 version  of  xdm,  the  default  xdm-config  file  looks  like  this: 


DisplayManager . servers : 
DisplayManager . errorLogFile : 
DisplayManager*resources : 
DisplayManager*startup : 
DisplayManager*session : 
DisplayManager*reset : 


/usr/lib/Xll/xdm/Xservers 

/usr/lib/Xll/xdm/xdm-errors 

/usr/lib/Xll/xdm/Xresources 

/usr/lib/Xll/xdm/Xstartup 

/usr/lib/Xll/xdm/Xsession 

/usr/lib/Xll/xdm/Xreset 


As  you  can  see,  the  xdm-config  file  primarily  contains  references  to  other  files.  Note  that  some 
of  the  resources  are  specified  with  *****  separating  the  components.  These  resources  can  be 
made  unique  for  each  different  display,  by  replacing  the  *****  with  the  display  name,  but  nor- 
mally this  is  not  very  useful.  See  the  “Resources”  section  for  a complete  discussion. 

The  first  file,  lusrllib/Xl  1 /xdm/X servers , contains  the  list  of  displays  to  manage.  Most  worksta- 
tions have  only  one  display,  numbered  0,  so  the  file  will  look  like  this: 
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:0  display_class  local  /usr/bin/Xll/X  :0 

This  will  keep  /usr/bin/Xll/X  running  on  this  display  and  manage  a continuous  cycle  of 
sessions. 

The  file  lusr/lib/Xl  1 /xdm/xdm-errors  will  contain  error  messages  from  xdm  and  anything  output 
to  standard  error  by  Xstartup,  Xsession  or  Xreset.  When  you  have  trouble  getting  xdm  working, 
check  this  file  to  see  if  x dm  has  any  clues  to  the  trouble. 

The  next  configuration  entry,  lusr/lib/Xl  1 /xdm/Xre sources , is  loaded  onto  the  display  as  a 
resource  database  using  xrdb.  As  the  authentication  widget  reads  this  database  before  starting 
up,  it  usually  contains  parameters  for  that  widget; 

xlogin* login . translations : #override\\e 

<Key>Fl:  set-session-argument (failsafe)  f inish-f ield ( ) \\en\\e 
<Key>Return:  set-session-argument ( ) f inish-f ield ( ) 
xlogin*borderWidth : 3 
#ifdef  COLOR 
xlogin*greetColor : #f63 
xlogin*failColor : red 
xlogin*Foreground : black 
xlogin*Background:  #fdc 
#else 

xlogin*Foreground : black 
xlogin*Background:  white 
#endif 

The  various  colors  specified  here  look  reasonable  on  several  of  the  displays  we  have,  but  may 
look  awful  on  other  monitors.  As  X does  not  currently  have  any  standard  color  naming  scheme, 
you  might  need  to  tune  these  entries  to  avoid  disgusting  results.  Please  note  the  translations 
entry;  it  specifies  a few  new  translations  for  the  widget  which  allow  users  to  escape  from  the 
default  session  (and  avoid  troubles  that  may  occur  in  it).  Note  that  if  #override  is  not  specified, 
the  default  translations  are  removed  and  replaced  by  the  new  value,  not  a very  useful  result  as 
some  of  the  default  translations  are  quite  useful  (like  <Key>:  insert-char  ( ) which 
responds  to  normal  typing). 

The  Xstartup  file  used  here  simply  prevents  login  while  the  file  /etc/nologin  exists.  As  there  is 
no  provision  for  displaying  any  messages  here  (there  isn’t  any  core  X client  which  displays 
files),  the  user  will  probably  be  baffled  by  this  behavior.  I don’t  offer  this  as  a complete 
example,  but  simply  a demonstration  of  the  available  functionality. 

Here  is  a sample  Xstartup  script: 

# ! /bin/ sh 

# 

# Xstartup 

# 

# This  program  is  run  as  root  after  the  user  is  verified 

# 

if  [ -f  /etc/nologin  ] ; then 
exit  1 
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fi 

exit  0 

The  most  interesting  script  is  Xsession.  This  version  recognizes  the  special  “failsafe”  mode, 
specified  in  the  translations  in  the  Xresources  file  above,  to  provide  an  escape  from  the  ordinary 
session: 


# ! /bin/ sh 
# 

# Xsession 

# 

# This  is  the  program  that  is  run  as  the  client 

# for  the  display  manager.  This  example  is 

# quite  friendly  as  it  attempts  to  run  a per-user 

# .xsession  file  instead  of  forcing  a particular 

# session  layout 

case  $#  in 
1) 

case  $1  in 
failsafe) 

exec  xterm  -geometry  80x24-0-0  -Is 


esac 

esac 

startup=$HOME/ . xsession 
resources=$HOME/ .Xresources 

# 

# check  for  a user-specific  session  and  execute  it 

# 

# Note:  the  -x  flag  to  test  is  not  supported  in  all  versions  of 

# unix,  check  with  local  authorities  before  proceeding  . . . 

# 

if  [ -f  $startup  ] ; then 

if  [ -x  $startup  ] ; then 
exec  $startup 

else 

exec  /bin/sh  $startup 
fi 

else 

# 

# a simple  default  session.  Check  to  see 

# if  the  user  has  created  a default  resource  file 
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# and  load  it,  start  the  universal  window  manager 

# and  use  xterm  as  the  session  control  process. 

# 

/ 

if  [ -f  $resources  ] ; then 

xrdb  -load  $resources 
fi 

twm  & 

exec  xterm  -geometry  80x24+10+10  -Is 
fi 

No  Xreset  script  is  necessary,  so  none  is  provided  in  Release  4.  (The  Release  3 sample  Xreset 
file  contains  nothing  but  a comment.) 

Some  Other  Possibilities 

You  can  also  use  xdm  to  run  a single  session  at  a time,  using  the  4.3  init  options  or  other  suit- 
able daemon  by  specifying  the  server  on  the  command  line: 

% xdm  -sarvar  ":0  SUN-3/60CG4  local  /usr/bin/X  :0" 

Or,  you  might  have  a file  server  and  a collection  of  X terminals.  The  configuration  for  this 
could  look  identical  to  the  sample  above,  except  the  Xservers  file  might  look  like: 

extol :0  VISUAL-19  foreign 

exalt :0  NCD-19  foreign 

explode :0  NCR-TOWERVIEW3000  foreign 

This  would  direct  xdm  to  manage  sessions  on  all  three  of  these  terminals.  See  “Controlling 
xdm”  above  for  a description  of  using  signals  to  enable  and  disable  these  terminals  in  a manner 
reminiscent  of  init. 

One  thing  that  xdm  isn’t  very  good  at  doing  is  coexisting  with  other  window  systems.  To  use 
multiple  window  systems  on  the  same  hardware,  you’ll  probably  be  more  interested  in  xinit. 

See  Also 

X,  xinit,  and  XDMCP 

Author 

Keith  Packard,  MIT  X Consortium. 
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Dump  Window  Directly  to  Printer — 


Name 

xdpr  - dump  an  X window  directly  to  the  printer. 

Syntax 

xdpr  [ filename ] [ options ] 


Description 

xdpr  runs  the  commands  xwd,  xpr , and  lpr(  1)  to  dump  an  X window,  process  it  for  a laser 
printer,  and  print  it  out.  This  is  the  easiest  way  to  get  a printout  of  a window,  xdpr  by  default 
will  print  the  largest  possible  representation  of  the  window  on  the  output  page. 

The  options  for  xdpr  are  the  same  as  those  for  xpr,  xwd,  and  lpr{  1).  The  most  commonly  used 
options  are  described  below;  see  the  reference  pages  for  these  commands  for  more  detailed 
descriptions  of  the  many  options  available. 


Options 

filename 


-P printer 


Specifies  an  existing  file  containing  a window  dump  (created  by  xwd)  to  be 
printed  instead  of  selecting  an  X window. 

Specifies  the  name  of  the  printer  to  be  used.  If  a printer  name  is  not  specified 
here,  xdpr  (really,  lpr(  1))  will  send  your  output  to  the  printer  specified  by  the 
PRINTER  environment  variable.  Be  sure  that  the  type  of  the  printer  matches 
the  type  specified  with  the  -device  option. 


-device  printer_device 

Specifies  the  device  on  which  the  file  is  to  be  printed.  Currently  the  follow- 
ing printers  are  supported: 


ln03 

Digital  LN03. 

lalOO 

Digital  LA  100. 

1 jet 

HP  LaserJet  series  and  other  monochrome  PCL  devices, 
such  as  ThinkJet,  QuietJet,  RuggedWriter,  HP2560  series, 
and  HP2930  series  printers.  (As  of  Release  4.) 

P jet 

HP  PaintJet  (color  mode).  (As  of  Release  4.) 

p jetxl 

HP  PaintJet  XL  Color  Graphics  Printer  (color  mode).  (As 
of  Release  4.) 

PP 

IBM  PP3812. 

ps 

PostScript  printer. 

Displays  the  list  of  options  known  to  xdpr. 

-display  [host]  : server[ . screen ] 

Allows  you  to  specify  the  server  to  connect  to.  host  specifies  the  machine, 
server  specifies  the  server  number,  and  screen  specifies  the  screen  num- 
ber. For  example, 

xdpr  -display  your  node: Q . 1 
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(continued) 


xdpr 


prints  a dump  of  an  X window  from  screen  1 of  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary 
in  all  cases. 

Any  other  arguments  will  be  passed  to  the  xwd , xpr,  and  lpr(  1)  commands  as  appropriate  for 

each. 

Environment  Variables 

PRINTER  Specifies  which  printer  to  use  by  default. 

See  Also 

X,  xwd,  xpr,  xwud,  lpr(l) 

Authors 

Paul  Boutin,  MIT  Project  Athena; 

Michael  R.  Gretzinger,  MIT  Project  Athena; 

Jim  Getty s,  MIT  Project  Athena. 
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Display  Information  Utility — 


\ 


Name 

xdpyinfo  - display  information  utility  for  X. 

Syntax 

xdpyinfo  [option] 

Description 

xdpyinfo  is  a utility  for  displaying  information  about  an  X server.  It  is  used  to  examine  the 
capabilities  of  a server,  the  predefined  values  for  various  parameters  used  in  communicating 
between  clients  and  the  server,  and  the  different  types  of  screens  and  visuals  that  are  available. 

Option 

-display  [ host ] : server[ . screen] 

Specifies  the  display  about  which  xdpyinfo  should  display  information,  host 
specifies  the  machine,  server  specifies  the  server  number,  and  screen 
specifies  the  screen  number.  By  default,  xdpyinfo  displays  information  about 
all  screens  on  the  display.  For  example, 

xdpyinfo  -display  your_node: 0.0 

displays  information  about  all  screens  of  server  0 of  the  machine 
your_node.  If  the  hostname  is  omitted,  the  local  node  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed.  The  server  and  colon  (:)  are  necessary 
in  all  cases. 

Sample  Output  (Release  4) 

The  following  shows  a sample  produced  by  the  Release  4 version  of  xdpyinfo  when  connected 
to  a display  that  supports  an  8 plane  screen  and  a 1 plane  screen. 

name  of  display:  :0.0 

version  number:  11.0 

vendor  string:  MIT  X Consortium 

vendor  release  number:  4 

maximum  request  size:  16384  longwords  (65536  bytes) 
motion  buffer  size:  0 

bitmap  unit,  bit  order,  padding:  32,  MSBFirst,  32 

image  byte  order:  MSBFirst 

number  of  supported  pixmap  formats:  2 

supported  pixmap  formats: 

depth  1,  bits_per j>ixel  1,  scanline_pad  32 
depth  8,  bits_per_pixel  8,  scanline_pad  32 
keycode  range:  minimum  8,  maximum  129 

number  of  extensions:  4 

SHAPE 
MIT-SHM 

Multi-Buffering 
MIT-SUNDRY-NONSTANDARD 
default  screen  number:  0 

number  of  screens:  2 
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'tsomnmcfi 
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scrw;  ♦! : 
dimensions: 
resolution: 
depths  «2J:  1. 

root  window  id: 


1152x903  pixels  1325x254  mlllimet ers? 
92x91  or*  s per  inch 
s 


" w 2"'.''  ST 


oec: 


ol  root  wm oc*r: 


note 

? planes 
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• Traximurr  _ 


'•st  ruot  ureFebirect.Kas«. 


r.jncer  of  color-nans: 
default  color-map:  2x$32€b 

deffaialt  number  of  colomap  oells:  256 

preallocsteo  pixels:  black  1.  xfeite  2 

options:  backing-store  YT>.  save-toners  TF? 

current  input  evert  irast:  2xo2521d 

KeyFressMas*  ftuttocFressMask  Sot  t otFe  lea  se.Va  s a 

lot  e r¥  t jadoMHa  5 c Expos  ureKas< 

Frnpert  yCbangeMask  Colo  nrapChanpesWa  s c 
number  of  visuals:  5 

default  visual  to:  1x51255 
visual : 

visual  id:  2x52255 

“lass:  Fse  adoGol  or 

depth:  5 plaoes 

sire  of  oolomac:  255  er tries 

red,  preen,  blue  nasxs:  1x2,  2x2,  2x2 

significant  bits  in  oolor  specification: 
vi sual : 

visual  id:  2x52255 

olass:  Ft reot Color 

depth:  5 plaoes 

sire  of  col  o mac:  5 entries 

red.  preen,  blue  nas<s:  2x'.  2x55,  2xo 


sipnifioant  bits  in 
visual : 


Mr  speoinoatior: 


vista,  id: 


. x: 


o.ass : 
depth : 
sire  o: 


Gray  >ca _ e 
5 plaoes 

r'C“  C*  ^'TTti.C  z 


ZSt  entries 

2x2,  2x2,  2x2 
specification: 


red.  preen,  blue  nas<s: 
significant  bits  in  col 
visual : 

visual  id:  2x51255 

class:  FtaticCray 

depth:  5 plaoes 

sire  of  colonup:  255  entries 

red,  preen,  blue  nasxs:  2x2,  2x2,  2x2 

significant  bits  in  color  specification: 
visual : 

visual  id:  2x52259 

class:  StaticColor 


5 cits 


5 bits 


e o-aoes 


depth: 
sire  of  cclonrao: 


255  entries 
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red,  green. 

blue  masks: 

0x7, 

0x38,  OxcO 

significant 

bits  in  color  specification: 

8 

bits 

visual : 

visual  id: 

0x8006a 

class:  TrueColor 

depth:  8 

planes 

size  of  colormap:  8 

entries 

red,  green. 

blue  masks: 

0x7, 

0x38,  OxcO 

significant 

bits  in  color  specification: 

8 

bits 

number  of  mono  multibuffer  types: 

6 

visual  id. 

max  buffers. 

depth: 

0x80065, 

o. 

8 

visual  id. 

max  buffers. 

depth: 

0x80066, 

0, 

8 

visual  id. 

max  buffers, 

depth: 

0x80067, 

0, 

8 

visual  id. 

max  buffers. 

depth: 

0x80068, 

0, 

8 

visual  id. 

max  buffers. 

depth: 

0x80069, 

0, 

8 

visual  id. 

max  buffers. 

depth : 

0x8006a, 

o. 

8 

number  of  stereo  multibuffer  types:  0 

screen  #1: 

dimensions:  1152x900  pixels  (325x254  millimeters) 

resolution:  90x90  dots  per  inch 

depths  ( 1 ) : 1 

root  window  id:  0x80070 

depth  of  root  window:  1 plane 

number  of  colormaps:  minimum  1,  maximum  1 

default  colormap:  0x8006c 

default  number  of  colormap  cells:  2 

preallocated  pixels:  black  1,  white  0 

options:  backing-store  YES,  save-unders  YES 

current  input  event  mask:  0xd0801d 

KeyPressMask  ButtonPressMask  ButtonReleaseMask 

EnterWindowMask  ExposureMask  SubstructureRedirectMask 

PropertyChangeMask  ColormapChangeMask 

number  of  visuals:  1 

default  visual  id:  0x80064 
visual : 

visual  id:  0x80064 

class:  StaticGray 

depth:  1 plane 

size  of  colormap:  2 entries 

red,  green,  blue  masks:  0x0,  0x0,  0x0 

significant  bits  in  color  specification:  1 bits 

number  of  mono  multibuffer  types:  1 

visual  id,  max  buffers,  depth:  0x80064,  0,  1 

number  of  stereo  multibuffer  types:  0 
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(continued) 


xdpyinfo 


Sample  Output  (Release  3) 

The  following  shows  a sample  produced  by  the  Release  3 version  of  xdpyinfo  when  connected 
to  a display  that  supports  an  8 plane  Pseudocolor  screen  as  well  as  a 1 plane  (monochrome) 
screen. 


name  of  display:  empire: 0.0 

version  number:  11.0 

vendor  string:  MIT  X Consortium 

vendor  release  number:  3 

maximum  request  size:  16384  longwords  (65536  bytes) 
motion  buffer  size:  0 

bitmap  unit,  bit  order,  padding:  32,  MSBFirst,  32 

image  byte  order:  MSBFirst 

keycode  range:  minimum  8,  maximum  129 

default  screen  number:  0 

number  of  screens:  2 


screen  #0: 

dimensions:  1152x900  pixels  (325x254  millimeters) 

resolution:  90x90  dots  per  inch 

root  window  id:  0x8006d 

depth  of  root  window:  1 plane 

number  of  colormaps:  minimum  1,  maximum  1 

default  colormap:  0x80065 

default  number  of  colormap  cells:  2 

preallocated  pixels:  black  1,  white  0 

options:  backing-store  YES,  save-unders  YES 

current  input  event  mask:  0xlb8003c 

ButtonPressMask  ButtonReleaseMask 

LeaveWindowMask  SubstructureNotifyMask 

FocusChangeMask  ColormapChangeMask 

number  of  visuals:  1 

default  visual  id:  0x80064 
visual : 

visual  id:  0x80064 

class:  StaticGray 

depth:  1 plane 

size  of  colormap:  2 entries 

red,  green,  blue  masks:  0x0,  0x0,  0x0 

significant  bits  in  color  specification: 


EnterWindowMask 

Subs tructureRedirect Mask 

OwnerGrabButtonMask 


1 bits 


screen  #1: 

dimensions:  1152x900  pixels  (325x254  millimeters) 

resolution:  90x90  dots  per  inch 

root  window  id:  0x80070 

depth  of  root  window:  8 planes 

number  of  colormaps:  minimum  1,  maximum  1 

default  colormap:  0x80067 

default  number  of  colormap  cells:  256 

preallocated  pixels:  black  1,  white  0 

options:  backing-store  YES,  save-unders  YES 
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current  input  event  mask:  0x0 

number  of  visuals:  1 

default  visual  id:  0x80066 
visual : 

visual  id:  0x80066 

class:  Pseudocolor 

depth:  8 planes 

size  of  colormap:  256  entries 

red,  green,  blue  masks:  0x0,  0x0,  0x0 

significant  bits  in  color  specification:  8 bits 


See  Also 

X,  xwininfo,  xprop,  xrdb 


Bugs  in  Release  3 

Due  to  a bug  in  the  Xlib  interface,  there  is  no  portable  way  to  determine  the  depths  of  pixmap 
images  that  are  supported  by  the  server. 


Author 

Jim  Fulton,  MIT  X Consortium. 
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xedit 


— Text  Editor  for  X 


/ 


Name 

xedit  - simple  text  editor  for  X. 

Syntax 

xedit  [options]  [filename] 

Description  of  the  Release  4 Client 

The  Release  4 version  of  xedit  provides  a window  consisting  of  the  following  four  areas: 
Commands  Section 

A set  of  commands  that  allow  you  to  exit  xedit,  save  the  file,  or  load  a new 
file  into  the  edit  window. 

Message  Window 

Displays  xedit  messages.  In  addition,  this  window  can  be  used  as  a scratch 
pad. 

Filename  Display 

Displays  the  name  of  the  file  currently  being  edited,  and  whether  this  file  is 
Read  - Write  or  Read  Only. 

Edit  Window  Displays  the  text  of  the  file  that  you  are  editing  or  creating. 

Editing  (Release  4) 

The  Athena  Text  widget  is  used  for  the  three  sections  of  this  application  that  allow  text  input. 
The  characters  typed  will  go  to  the  Text  widget  that  the  pointer  cursor  is  currently  over.  If  the 
pointer  cursor  is  not  over  a text  widget  then  the  keypresses  will  have  no  effect  on  the  applica- 
tion. This  is  also  true  for  the  special  key  sequences  that  popup  dialog  widgets,  so  typing  Con- 
trol-S  in  the  filename  widget  will  enable  searching  in  that  widget,  not  the  edit  widget. 

Both  the  message  window  and  the  edit  window  will  create  a scrollbar  if  the  text  to  display  is 
too  large  to  fit  in  that  window.  Horizontal  scrolling  is  not  allowed  by  default,  but  can  be  turned 
on  through  the  Text  widget’s  resources,  see  Athena  Widget  set  documentation  for  the  exact 
resource  definition. 

Commands  (Release  4) 

Quit  Quits  the  current  editing  session.  If  any  changes  have  not  been  saved,  xedit 

displays  a warning  message,  allowing  the  user  to  save  the  file. 

Save  If  file  backups  are  enabled  (see  “Resources”)  xedit  stores  a copy  of  the  origi- 

nal, unedited  file  in  <prefix>/ite<suffix>,  then  overwrites  the  file  with  the 
contents  of  the  edit  window.  The  filename  is  retrieved  from  the  Text  widget 
directly  to  the  right  of  the  Load  button. 

Load  Loads  the  file  named  in  the  text  widget  immediately  to  the  right  of  the  this 

button  and  displays  it  in  the  Edit  Window.  If  the  currently  displayed  file  has 
been  modified  a warning  message  will  ask  the  user  to  save  the  changes,  or 
press  Load  again. 

Description  of  the  Release  3 Client 

The  Release  3 version  of  xedit  provides  a window  consisting  of  the  following  three  areas: 
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(continued) 


Text  Editor  for  X 


Commands  Menu 

Lists  editing  commands  (for  example,  Undo  or  Search). 

Message  Window 

Displays  xedit  messages.  In  addition,  this  window  can  be  used  as  a scratch 
pad. 

Edit  Window  Displays  the  text  of  the  file  that  you  are  editing  or  creating. 

Commands  (Release  3) 


Quit 

Quits  the  current  editing  session.  If  any  changes  have  not  been  saved,  xedit 
displays  a warning  message  and  allows  you  to  save  the  file. 

Save 

Stores  a copy  of  the  original,  unedited  file  in  file. BAK.  Then,  overwrites  the 
original  file  with  the  edited  contents. 

Edit 

Allows  the  text  displayed  in  the  Edit  window  to  be  edited. 

Load 

Loads  the  specified  file  and  displays  it  in  the  Edit  window. 

Undo 

Undoes  the  last  edit  only. 

More 

Undoes  each  edit  previous  to  the  last  edit,  which  must  first  be  undone  with 
the  Undo  command. 

Jump 

Advances  the  cursor  from  the  beginning  of  the  file  to  the  text  line  that  corre- 
sponds to  the  selected  line  number. 

« 

Searches  from  the  cursor  back  to  the  beginning  of  the  file  for  the  string 
entered  in  the  Search  input  box.  If  you  do  not  enter  a string  in  the  Search 
input  box,  xedit  automatically  copies  the  last  string  that  you  selected  from 
any  X application  into  the  Search  input  box  and  searches  for  that  string. 

Search  » 

Searches  from  the  cursor  forward  to  the  end  of  the  file  for  the  string  entered 
in  the  search  input  box.  If  you  do  not  enter  a string  in  the  Search  input  box, 
xedit  automatically  copies  the  last  string  that  you  selected  from  any  X appli- 
cation into  the  Search  input  box  and  searches  for  that  string. 

Replace 

Replaces  the  last  searched-for  string  with  the  string  specified  in  the  Replace 
input  box.  If  no  string  has  been  previously  searched  for,  searches  from  the 
insert  cursor  to  the  end  of  the  file  for  the  next  occurrence  of  the  search  string 
and  highlights  it. 

All 

Repositions  the  cursor  at  the  beginning  of  the  file  and  replaces  all  occur- 
rences of  the  search  string  with  the  string  specified  in  the  Replace  input  box. 

Options 

xedit  accepts  all  of  the  standard  X Toolkit  command  line  options,  as  well  as  the  following: 

filename 

Specifies  the  file  that  is  to  be  loaded  during  start-up.  This  is  the  file  that  will 
be  edited.  If  a file  is  not  specified,  xedit  lets  you  load  a file  or  create  a new 
file  after  it  has  started  up. 
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(continued) 


xedit 


Widgets  (Release  4) 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  which  compose 
xedit.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  the  widget  instance  name. 


Xedit  xedit 

Paned  paned 

Paned  buttons 


Label 

Text 

Label 

Text 


Command  quit 
Command  save 
Command  load 
Text  filename 

bc_label 
messageWindow 
labelWindow 
editWindow 


Resources  (Release  4) 

For  the  Release  4 version  of  xedit , the  available  resources  are: 

enableBackups  (class  EnableBackups) 

Specifies  that,  when  edits  made  to  an  existing  file  are  saved,  xedit  is  to  copy 
the  original  version  of  that  file  to  <prefix>/t/e<suffix>  before  it  saves  the 
changes.  The  default  value  for  this  resource  is  “off’,  stating  that  no  backups 
should  be  created. 

backupNamePref ix  (class  BackupNamePref  ix) 

Specifies  a string  that  is  to  be  prepended  to  the  backup  filename.  The  default 
is  that  no  string  shall  be  prepended. 

backupNameSuf  f ix  (class  BackupNameSuf  f ix) 

Specifies  a string  that  is  to  be  appended  to  the  backup  filename.  The  default 
is  to  append  the  string  “.BAK”. 

Resources  (Release  3) 

For  the  Release  3 verion  of  xedit,  the  available  class  identifiers  are: 


ButtonBox  The  two  boxes  containing  command  buttons. 

Command  All  command  buttons. 

Scrollbar  The  two  scroll  bars. 

Text  The  two  text  areas. 

The  available  name  identifiers  are: 

All 

Edit 

EditWindow 

Jump 
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(continued) 


Text  Editor  for  X 


Load 

MessageWindow 
More 
Quit 
Replace 
Save 
Undo 
xedit 

The  name  identifiers  for  the  various  buttons  are  the  same  as  the  string  on  each  button.  The 
resources  for  individual  buttons  can  be  set  using  these  names.  All  of  the  buttons  can  be 
affected  by  using  the  Command  class.  The  resources  for  the  two  text  windows  can  be  modified 
using  the  names  EditWindow  and  MessageWindow. 

Beyond  the  standard  resources,  xedit' s resources  are: 

EnableBackups 

Specifies  that,  when  edits  made  to  an  existing  file  are  saved,  xedit  is  to  copy 
the  original  version  of  that  file  to  file.  BAK  before  it  saves  the  changes.  If  the 
value  of  this  option  is  specified  as  off,  a backup  file  is  not  created. 

Specifies  the  background  color  to  be  displayed  in  command  buttons.  The 
default  is  white. 

Specifies  the  border  color  of  the  xedit  window. 

Specifies  the  border  width,  in  pixels,  of  the  xedit  window. 

Specifies  the  font  displayed  in  the  xedit  window. 

Specifies  the  foreground  color  of  the  xedit  window.  The  default  is  black. 

Specifies  the  geometry  (window  size  and  screen  location)  to  be  used  as  the 
default  for  the  xedit  window.  For  the  format  of  the  geometry  specification, 
see  X. 

interna lHeight 

Specifies  the  internal  horizontal  padding  (spacing  between  text  and  button 
border)  for  command  buttons. 

interna lWidth 

Specifies  the  internal  vertical  padding  (spacing  between  text  and  button  bor- 
der) for  command  buttons. 

Key  Bindings  (Release  3) 

Each  specification  included  in  the  XtActions  file  modifies  a key  setting  for  the  editor  that  xedit 
uses.  When  defining  key  specifications,  you  must  use  the  following  resource  specification: 

xedit  *text . EventBindings : . XtActions 

Each  key  specification  assigns  an  editor  command  to  a named  key  and/or  mouse  combination 
and  has  the  format: 


background 

border 

borderWidth 

font 

foreground 

geometry 
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key : 
where 


function 


key 

function 


Specifies  the  key  or  mouse  button  that  is  used  to  invoke  the  named  function. 
Specifies  the  function  to  be  invoked  when  the  named  key  is  pressed. 


Files 


lusrlliblXl  1 lapp-defaultsIXedit  - Specifies  required  resources  (Release  4) 

7 XtActions  (Release  3 only) 
lusrlliblXl  1 / XtActions  (Release  3 only) 

Restrictions  in  Release  4 

There  is  no  undo  function. 

Restrictions  in  Release  3 

Large  numbers  of  certain  edit  functions  (for  example,  Undo  or  More)  tend  to  degrade  perfor- 
mance over  time.  If  there  is  a noticeable  decrease  in  response  time,  save  and  reload  the  file. 

Bugs  in  Release  3 

It  is  not  clear  how  to  select  a line  number  for  the  Jump  command. 

The  string  searches  do  not  work  properly. 

See  Also 

X,  xrdb,  Athena  Widget  set  documentation 

Copyright 

Copyright  © 1988,  Digital  Equipment  Corporation.  Copyright  © 1989,  Massachusetts  Institute 
of  Technology. 

Author 

Chris  D.  Peterson,  MIT  X Consortium. 
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Print  X Events — 


Name 

xev  - print  contents  of  X events. 

Syntax 

xev  [options] 

Description 

xev  creates  a window  and  then  asks  the  X server  to  send  it  notices  called  events  whenever  any- 
thing happens  to  the  window  (such  as  being  moved,  resized,  typed  in,  clicked  in,  etc.).  It  is  use- 
ful for  seeing  what  causes  events  to  occur  and  to  display  the  information  that  they  contain. 

xev  is  included  in  the  Release  3 standard  distribution;  in  Release  4,  it  has  been  moved  to  demos. 

Options 

-display  [ host]  : server[ . screen ] 

Allows  you  to  specify  the  host,  server,  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

x«v  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  xev  window  is  created  with  the  specified  size  and  location  determined  by 
the  supplied  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) -s  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 


See  Also 

X,  xwininfo,  xdpyinfo;  Volume  One,  Xlib  Programming  Manual ; Volume  Zero,  X Protocol 
Reference  Manual. 


Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xfd  - X window  font  displayer. 

Syntax 

xfd  [options]  -fn  forxtname 


Description  of  the  Release  4 Client 

The  Release  4 version  of  xfd  creates  a window  containing  the  name  of  the  font  being  displayed, 
a row  of  command  buttons,  several  lines  of  text  for  displaying  character  metrics,  and  a grid 
containing  one  glyph  per  cell.  The  characters  are  shown  in  increasing  order  from  left  to  right, 
top  to  bottom.  The  first  character  displayed  at  the  top  left  will  be  character  number  0 unless  the 
-start  option  has  been  supplied  in  which  case  the  character  with  the  number  given  in  the 
-start  option  will  be  used. 


The  characters  are  displayed  in  a grid  of  boxes,  each  large  enough  to  hold  any  single  character 
in  the  font  Each  character  glyph  is  drawn  using  the  PolyTextl6  request  (used  by  the  Xlib 
routine  XDrawStringl6).  If  the  -box  option  is  given,  a rectangle  will  be  drawn  around 
each  character,  showing  where  an  lmageTextl6  request  (used  by  the  Xlib  routine  XDraw- 
lmageStringl6)  would  cause  background  color  to  be  displayed. 


The  origin  of  each  glyph  is  normally  set  so  that  the  character  is  drawn  in  the  upper  left  hand 
comer  of  the  grid  cell.  However,  if  a glyph  has  a negative  left  bearing  or  an  unusually  large 
ascent,  descent,  or  right  bearing  (as  is  the  case  with  the  cursor  font),  some  character  may  not 
appear  in  their  own  grid  cells.  The  -center  option  may  be  used  to  force  all  glyphs  to  be  cen- 
tered in  their  respective  cells. 


All  the  characters  in  the  font  may  not  fit  in  the  window  at  once.  To  see  the  next  page  of  glyphs, 
press  the  Next  button  at  the  top  of  the  window.  To  see  the  previous  page,  press  Prev.  To  exit 
xfd,  press  Quit. 


Individual  character  metrics  (index,  width,  bearings,  ascent  and  descent)  can  be  displayed  at 
the  top  of  the  window  by  pressing  on  the  desired  character. 

The  font  name  displayed  at  the  top  of  the  window  is  the  full  name  of  the  font,  as  determined  by 
the  server.  See  xlsfonts  for  ways  to  generate  lists  of  fonts,  as  well  as  more  detailed  summaries 
of  their  metrics  and  properties. 


Description  of  the  Release  3 Client 

The  Release  3 version  of  xfd  creates  a window  in  which  the  characters  in  the  named  font  are 
displayed.  The  characters  are  shown  in  increasing  order  from  left  to  right,  top  to  bottom.  The 
first  character  displayed  at  the  top  left  will  be  character  number  0 unless  the  -start  option 
has  been  supplied  in  which  case  the  character  with  the  number  given  in  the  -start  option 
will  be  used. 

The  characters  are  displayed  in  a grid  of  boxes,  each  large  enough  to  hold  any  character  in  the 
font.  If  the  -gray  option  has  been  supplied,  the  characters  will  be  displayed  using  the  Xlib 
routine  XDrawlmageString  using  the  foreground  and  background  colors  on  a gray  back- 
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ground.  This  permits  determining  exactly  how  XDrawlmageString  will  draw  any  given 
character.  If  -gray  has  not  been  supplied,  the  characters  will  simply  be  drawn  using  the  fore- 
ground color  on  the  background  color. 

All  the  characters  in  the  font  may  not  fit  in  the  window  at  once.  To  see  additional  characters, 
click  the  right  mouse  button  on  the  window.  This  will  cause  the  next  window  full  of  characters 
to  be  displayed.  Clicking  the  left  mouse  button  on  the  window  will  cause  the  previous  window 
full  of  characters  to  be  displayed,  xfd  will  beep  if  an  attempt  is  made  to  go  back  past  the  Oth 
character. 

Note  that  if  the  font  is  a 8 bit  font,  the  characters  256-511  (OxlOO-Oxlff  in  hexidecimal), 
512-767  (0x200-0x2ff),  etc.,  will  display  exactly  the  same  as  the  characters  0-255  (OxOO-Oxff). 
xfd  by  default  creates  a window  big  enough  to  display  the  first  256  characters  using  a 16  by  16 
grid.  In  this  case,  there  is  no  need  to  scroll  forward  or  backward  window  fulls  in  order  to  see 
the  entire  contents  of  a 8 bit  font.  Of  course,  this  window  may  very  well  not  fit  on  the  screen. 

Clicking  the  middle  button  on  a character  will  cause  that  character’s  number  to  be  displayed  in 
both  decimal  and  hexidecimal  at  the  bottom  of  the  window.  If  verbose  mode  is  selected,  addi- 
tional information  about  that  particular  character  will  be  displayed  as  well.  The  displayed 
information  includes  the  width  of  the  character,  its  left  bearing,  right  bearing,  ascent,  and 
descent.  If  verbose  mode  is  selected,  typing  ’<’  or  ’>’  into  the  window  will  display  the  mini- 
mum or  maximum  values  respectively  taken  on  by  each  of  these  fields  over  the  entire  font 

The  fontname  is  interpreted  by  the  X server.  To  obtain  a list  of  all  the  fonts  available,  use 
xl  fonts. 

The  window  stays  around  until  the  xfd  process  is  killed  or  one  of  ’q\  ’Q’,  ’ or  Control-C  is 
typed  into  the  xfd  window. 

Options  (Release  4) 

The  Release  4 version  of  xfd  accepts  all  of  the  standard  X Toolkit  command  line  options,  as 
well  as  the  following  additional  options.  The  option  -f n font  is  required. 

-f n font  Specifies  the  font  to  be  displayed. 

-box  Indicates  that  a box  outlining  the  area  that  would  be  filled  with  background 

color  by  an  imageText  request. 

-center  Indicates  that  each  glyph  should  be  centered  in  its  grid. 

-start  char_num 

Specifies  that  character  number  char_num  should  be  the  first  character 
displayed.  (It  appears  in  the  upper  left  hand  comer  of  the  grid.)  This  option 
is  used  to  view  characters  at  arbitrary  locations  in  the  font.  The  default  is  0. 

-be  color  Specifies  the  color  to  be  used  if  ImageText  boxes  are  drawn. 

Options  (Release  3) 

The  Release  3 version  of  xfd  accepts  the  following  options.  The  option  -f  n font  is  required, 
-fn  font  Specifies  the  font  to  be  displayed. 
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-bw  pixel  s Allows  you  to  specify  the  width  of  the  window  border  in  pixels. 

-rv  Specifies  that  the  foreground  and  background  colors  be  switched.  The  default 

colors  are  black  on  white. 

-fw  Overrides  a previous  choice  of  reverse  video.  The  foreground  and  back- 

ground colors  will  not  be  switched. 


-f  g col  or  On  color  displays,  determines  the  foreground  color  (the  color  of  the  text), 

-bg  color  On  color  displays,  determines  the  background  color. 

-bd  col  or  On  color  displays,  determines  the  color  of  the  border. 

-bf  fontname 

Specifies  the  font  to  be  used  for  the  messages  at  the  bottom  of  the  window, 
-t  1 title  Specifies  that  the  title  of  the  displayed  window  should  be  title. 

-in  iconname 


Specifies  that  the  name  of  the  icon  should  be  iconname. 

-icon  filename 

Specifies  that  the  bitmap  in  file  filename  should  be  used  for  the  icon. 

-verbose  Specifies  that  verbose  mode  should  be  used  (i.e.,  extra  information  about  the 
font  should  be  displayed). 

-gray  Specifies  that  a gray  background  should  be  used. 

-start  char_num 

Specifies  that  character  number  char_num  should  be  the  first  character 
displayed.  (It  appears  in  the  upper  left  hand  comer  of  the  grid.)  This  option 
is  used  to  view  characters  at  arbitrary  locations  in  the  font.  The  default  is  0. 


-geometry  geometry 

Specifes  the  size  and  location  of  the  xfd  window.  The  -geometry  option 
can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option 
that  begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 

-display  [host]:server[.screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  create  the  xfd 
window,  host  specifies  the  machine  on  which  to  create  the  xfd  window, 
server  specifies  the  server  number,  and  screen  specifies  the  screen  num- 
ber. For  example, 


xfd  -display  your_n ode: 0.1 

creates  a window  on  screen  1 of  server  0 on  the  machine  your_node.  If  the 
host  is  omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the 
screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 
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Resources  (Release  4) 

The  Release  4 version  of  xfd  was  written  with  the  X Toolkit  Intrinsics.  xfd  accepts  the  follow- 
ing resources,  which  are  accepted  by  most  applications  written  with  the  Toolkit: 

background  (class  Background) 

Specifies  the  color  to  use  for  the  window  background. 

borderWidth  (class  BorderWidth) 

Specifies  the  width  in  pixels  of  the  window  border. 

borderColor  (class  BorderColor) 

Specifies  the  color  to  use  for  the  window  border. 

foreground  (class  Foreground) 

Specifies  the  color  to  use  for  text  and  graphics  within  the  window. 


Resources  (Release  3) 

The  Release  3 xfd  program  uses  the  following  resources: 
BorderWidth  Set  the  border  width  of  the  window  in  pixels. 
BorderColor  Set  the  border  color  of  the  window. 
ReverseVideo 


Foreground 

Background 

BodyFont 


IconName 

IconBitmap 

Title 


If  “on”,  reverse  the  definition  of  foreground  and  background  color. 

Set  the  foreground  color. 

Set  the  background  color. 

Set  the  font  to  be  used  in  the  body  of  the  window  (i.e.,  for  messages).  This  is 
not  the  font  that  xfd  displays;  it  is  the  font  used  to  display  information  about 
the  font  being  displayed. 

Set  the  name  of  the  icon. 

Set  the  file  we  should  look  in  to  get  the  bitmap  for  the  icon. 

Set  the  title  to  be  used. 


Bugs  in  Release  4 

xfd  should  skip  over  pages  full  of  non-existent  characters. 

Bugs  in  Release  3 

Character  information  displayed  in  verbose  mode  is  sometimes  clipped  to  the  window  bound- 
ary hiding  it  from  view. 

xfd  should  skip  over  pages  full  of  non-existent  characters. 

See  Also 

X,  xfontsel,  xlsfonts,  xrdb 
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Release  4 version  by  Jim  Fulton,  MIT  X Consortium; 

Release  3 version  by  Mark  Lillibridge,  MIT  Project  Athena. 
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Name 

xfontsel  - point  and  click  interface  for  selecting  display  font  names. 

Syntax 

xfontsel  [options] 

Description 

Available  as  of  Release  4,  xfontsel  provides  a simple  way  to  display  the  fonts  known  to  your  X 
server,  examine  samples  of  each,  and  retrieve  the  X Logical  Font  Description  (XLFD)  full 
name  for  a font. 

If  -pattern  is  not  specified,  all  fonts  with  XLFD  14-part  names  will  be  selectable.  To  work 
with  only  a subset  of  the  fonts,  specify  -pattern  followed  by  a partially  or  fully  qualified 
font  name.  For  example, 

% xfontsal  -pattern  * medium* 

will  select  the  subset  of  fonts  that  contain  the  string  medium  somewhere  in  their  font  name. 
Be  careful  about  escaping  wildcard  characters  in  your  shell. 

If  -print  is  specified  on  the  command  line  the  selected  font  specifier  will  be  written  to  stan- 
dard output  when  the  quit  button  is  activated.  Regardless  of  whether  or  not  -print  was 
specified,  the  font  specifier  may  be  made  the  (text)  selection  by  activating  the  select  button. 

Clicking  any  pointer  button  in  one  of  the  XLFD  field  names  will  pop  up  a menu  of  the  cur- 
rently-known possibilities  for  that  field.  If  previous  choices  of  other  fields  were  made,  only 
values  for  fonts  which  matched  the  previously  selected  fields  will  be  selectable;  to  make  other 
values  selectable,  you  must  deselect  some  other  field(s)  by  choosing  the  entry  in  that  field. 
Unselectable  values  may  be  omitted  from  the  menu  entirely  as  a configuration  option;  see  the 
ShowUnselec table  resource,  below.  Whenever  any  change  is  made  to  a field  value, 
xfontsel  will  assert  ownership  of  the  PRIMARY_FONT  selection.  Other  applications  (such  as 
xterm)  may  then  retrieve  the  selected  font  specification. 

Clicking  the  left  pointer  button  in  the  select  widget  will  cause  the  currently  selected  font  name 
to  become  the  PRIMARY  text  selection  as  well  as  the  PRIMARY_FONT  selection.  Then  you  can 
paste  the  string  into  other  applications.  The  select  button  remains  highlighted  to  remind  you 
of  this  fact,  and  de-highlights  when  some  other  application  takes  the  PRIMARY  selection  away. 
The  select  widget  is  a toggle;  pressing  it  when  it  is  highlighted  will  cause  xfontsel  to  release 
the  selection  ownership  and  de-highlight  the  widget.  Activating  the  select  widget  twice  is  the 
only  way  to  cause  xfontsel  to  release  the  PRIMARY_FONT  selection. 
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Options 

xfontsel  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  described  below. 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  display  the 
xfontsel  window,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 

xfontsel  -display  your_node : 0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  colon  (;)  is  necessary  in  either  case. 

-pattern  fontname 

Specifies  a subset  of  the  available  fonts,  those  with  names  that  contain 
fontname,  which  can  be  a partial  or  full  name. 

-print  Specifies  that  the  selected  font  will  be  written  to  standard  output  when  the 

quit  button  is  activated. 

-sample  text 

Specifies  the  sample  text  to  be  used  to  display  the  selected  font,  overriding 
the  default  (the  lower  and  uppercase  alphabet  and  the  digits  0 through  9). 

Resources 

The  application  class  is  XFontSel.  Most  of  the  user-interface  is  configured  in  the  app- 
defaults  file;  if  this  file  is  missing  a warning  message  will  be  printed  to  standard  output  and  the 
resulting  window  will  be  nearly  incomprehensible. 

Most  of  the  significant  parts  of  the  widget  hierarchy  are  documented  in  the  app-defaults  file 
(normally  /usr/lib/Xlllapp-defaultsIXFontSel ). 

Application  specific  resources: 

cursor  (class  Cursor) 

Specifies  the  cursor  for  the  application  window. 

pattern  (class  Pattern) 

Specifies  the  font  name  pattern  for  selecting  a subset  of  available  fonts. 
Equivalent  to  the  -pattern  option.  Most  useful  patterns  will  contain  at 
least  one  field  delimiter,  for  example,  *-m-*  for  monospaced  fonts. 
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printOnQuit  (class  PrintOnQuit) 

If  True,  the  currently  selected  font  name  is  printed  to  standard  output  when 
the  quit  button  is  activated.  Equivalent  to  the  -print  option. 

Widget-specific  resources: 

showUnselectable  (class  ShowUnselectable) 

For  each  field  menu,  specifies  whether  or  not  to  show  values  that  are  not  cur- 
rently selectable,  based  upon  previous  field  selections.  If  shown,  the 
unselectable  values  are  clearly  identified  as  such  and  do  not  highlight  when 
the  pointer  is  moved  down  the  menu.  The  full  instance  name  of  this  resource 
is  f ieldN. menu . options . showUnselectable,  class  Menu- 
Button . SimpleMenu  . Options  . ShowUnselectable;  where  N is 
replaced  with  the  field  number  (starting  with  the  left-most  field  numbered  0). 
The  default  is  True  for  all  but  field  1 1 (average  width  of  characters  in  font) 
and  False  for  field  11.  If  you  never  want  to  see  unselectable  entries, 
*menu . options  . showUnselectable  : False  is  a reasonable  thing 
to  specify  in  a resource  file. 


Files 

lusrllib/Xl  1 lapp-defaults/XFontSel  - Specifies  default  resources. 


See  Also 

xrdb 


Bugs 

Sufficiently  ambiguous  patterns  can  be  misinterpreted  and  lead  to  an  initial  selection  string 
which  may  not  correspond  to  what  the  user  intended  and  which  may  cause  the  initial  sample 
text  output  to  fail  to  match  the  proffered  string.  Selecting  any  new  field  value  will  correct  the 
sample  output,  though  possibly  resulting  in  no  matching  font. 

Should  be  able  to  return  a font  for  the  PRIMARY  selection,  not  just  a string. 

Any  change  in  a field  value  will  cause  xfontsel  to  assert  ownership  of  the  PRIMARY_FONT 
selection.  Perhaps  this  should  be  parameterized. 

When  running  on  a slow  machine,  it  is  possible  for  the  user  to  request  a field  menu  before  the 
font  names  have  been  completely  parsed.  An  error  message  indicating  a missing  menu  is 
printed  to  standard  error,  but  otherwise  nothing  happens. 
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Ralph  R.  Swick,  Digital  Equipment  Corporation/MIT  Project  Athena. 
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Name 

xhost  - server  access  control  program  for  X. 


Syntax 

xhost  [ options ] 


Description 

The  xhost  program  is  used  to  add  and  delete  hosts  to  and  from  the  list  of  machines  that  are 
allowed  to  make  connections  to  the  X server.  This  provides  a rudimentary  form  of  privacy  con- 
trol and  security.  It  is  only  sufficient  for  a workstation  (single  user)  environment,  although  it 
does  limit  the  worst  abuses.  Environments  that  require  more  sophisticated  measures  should  use 
the  hooks  in  the  protocol  for  passing  authentication  data  to  the  server. 

The  server  initially  allows  network  connections  only  from  programs  running  on  the  same 
machine  or  from  machines  listed  in  the  file  /etc/Xn.hosts  (where  n is  the  display  number  of  the 
server).  The  xhost  program  is  usually  run  either  from  a startup  file  or  interactively  to  give 
access  to  other  users. 

Hostnames  that  are  followed  by  two  colons  (::)  are  used  in  checking  DECnet  connections;  all 
other  hostnames  are  used  for  TCP/IP  connections. 

If  no  command  line  options  are  given,  the  list  of  hosts  that  are  allowed  to  connect  is  printed  on 
the  standard  output  along  with  a message  indicating  whether  or  not  access  control  is  currently 
enabled.  This  is  the  only  option  that  may  be  used  from  machines  other  than  the  one  on  which 
the  server  is  running. 


Options 

xhost  accepts  the  command  line  options  described  below.  For  security,  the  options  that  affect 
access  control  may  only  be  run  from  the  same  machine  as  the  server. 

[+]hostname  The  given  hostname  (the  plus  sign  is  optional)  is  added  to  the  list  of 
machines  that  are  allowed  to  connect  to  the  X server. 


-hostname  The  given  hostname  is  removed  from  the  list  of  machines  that  are  allowed 
to  connect  to  the  server.  Existing  connections  are  not  broken,  but  new  con- 
nection attempts  will  be  denied.  Note  that  the  current  machine  is  allowed  to 
be  removed;  however,  further  connections  (including  attempts  to  add  it  back) 
will  not  be  permitted.  Resetting  the  server  (thereby  breaking  all  connections) 
is  the  only  way  to  allow  local  connections  again. 

+ Access  is  granted  to  everyone,  even  if  they  aren’t  on  the  list  of  allowed  hosts 

(i.e.,  access  control  is  turned  off). 

Access  is  restricted  to  only  those  machines  on  the  list  of  allowed  hosts  (i.e., 
access  control  is  turned  on). 


Files 

/etc/Xn.hosts 
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Bugs 

You  can’t  specify  a display  on  the  command  line  because  -display  indicates  that  you  want 
to  remove  the  machine  named  display  from  the  access  list. 

See  Also 

X,  Xserver 

Authors 

Bob  Scheifler,  MIT  Laboratory  for  Computer  Science; 

Jim  Gettys,  MIT  Project  Athena  (DEC). 
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\ 


Name 

xinit  - X Window  System  initializer. 

Syntax 

xinit  [[client]  options]  [ — [server program] 

[-display  [host] : server[ . screen]]  options ] 

Description 

The  xinit  program  is  used  to  start  the  X Window  System  server  program  and  a first  client  pro- 
gram (usually  a terminal  emulator)  on  systems  that  cannot  start  X directly  from  /etc/init  or  in 
environments  that  use  multiple  window  systems.  When  this  first  client  exits,  xinit  will  kill  the 
X server  program  and  then  terminate. 

If  no  specific  client  program  is  given  on  the  command  line,  xinit  will  look  in  the  user’s  home 
directory  for  a file  called  xinitrc  to  run  as  a shell  script  to  start  up  other  client  programs.  If  no 
such  file  exists,  xinit  will  use  the  following  xterm  command  line  as  a default: 

xtarm  -gaomatry  +1+1  -n  login  -display  :0 

If  no  specific  server  program  is  given  on  the  command  line,  xinit  will  look  in  the  user’s  home 
directory  for  a file  called  xserverrc  to  run  as  a shell  script  to  start  up  the  server.  If  no  such  file 
exists,  xinit  will  use  the  following  as  a default  server  specification: 

X : 0 

Note  that  this  assumes  that  there  is  a server  program  called  X in  the  current  search  path.  How- 
ever, servers  are  usually  named  Xdisplaytype , where  displaytype  is  the  type  of  graphics  display 
which  is  driven  by  the  server  (for  example,  Xsun ).  The  site  administrator  should  therefore 
make  a link  to  the  appropriate  type  of  server  on  the  machine  (see  Chapter  2,  Getting  Started,  in 
Part  One  of  this  guide  for  details),  or  create  a shell  script  that  runs  xinit  with  the  appropriate 
server. 

Note  that  programs  run  by  xinitrc  and  by  xserverrc  should  be  run  in  the  background  if  they  do 
not  exit  right  away,  so  that  they  don’t  prevent  other  programs  from  starting  up.  However,  the 
last  long-lived  program  started  (usually  a window  manager  or  terminal  emulator)  should  be  left 
in  the  foreground  so  that  the  script  won’t  exit  (which  indicates  that  the  user  is  done  and  that 
xinit  should  exit). 

An  alternate  client  and/or  server  may  also  be  specified  on  the  command  line.  The  desired  client 
program  and  its  arguments  should  be  given  as  the  first  command  line  arguments  to  xinit.  To 
specify  a particular  server  program,  append  a double  dash  (--)  to  the  xinit  command  line  (after 
any  client  and  arguments)  followed  by  the  desired  server  program. 

Both  the  client  program  name  and  the  server  program  name  must  begin  with  a slash  (/)  or  a 
period  (.);  otherwise,  they  are  treated  as  an  arguments  to  be  appended  to  their  respective  startup 
lines.  This  makes  it  possible  to  add  arguments  (for  example,  foreground  and  background 
colors)  without  having  to  retype  the  whole  command  line. 

If  an  explicit  server  name  is  not  given  and  the  first  argument  following  the  double  dash  (--)  is  a 
colon  followed  by  a digit,  xinit  will  use  that  number  as  the  display  number  instead  of  zero.  All 
remaining  arguments  are  appended  to  the  server  command  line. 
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Note  that  you  can  start  X manually  by  running  xinit  from  the  command  line  or  start  it  automati- 
cally by  adding  the  xinit  command  line  to  your  .login  or  .profile  file.  (See  Appendix  A,  System 
Management,  for  more  information.) 

Options 

client  Specifies  the  client  to  be  started  with  the  server. 

server_program 

Specifies  the  server  program  to  be  used. 

-display  [ host] : server[.screen] 

Specifies  the  host,  server  and  screen  on  which  you  are  initializing  the  X Win- 
dow System.  For  example, 

xinit.  -display  your_node : 0 . 1 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  any  case. 

Examples 

xinit  Will  start  up  a server  named  X and  run  the  user’s  ocinitrc,  if  it  exists,  or  else 

start  an  xterm. 

xinit  --  /usr/bin/Xll/Xqdss  :1 

Is  how  one  could  start  a specific  type  of  server  on  an  alternate  display. 

xinit  -geometry  80x65+10+10  -fn  8x13  - j -fg  white  -bg  navy 

Will  start  up  a server  named  X,  and  will  append  the  given  arguments  to  the 
default  xterm  command.  It  will  ignore  ocinitrc. 

xinit  -e  widgets  --  Xsun  -1  -c 

Will  use  the  command  ./Xsun  -l  -c  to  start  the  server  and  will  append  the 
arguments  -e  widgets  to  the  default  xterm  command. 

xinit  rsh  fasthost  cpupig  -display  workstation:  1 - - 1 -a  2 -t  5 

Will  start  a server  named  X on  display  1 with  the  arguments  -a  2 -t  5.  It  will 
then  start  a remote  shell  on  the  machine  fasthost  in  which  it  will  run  the  com- 
mand cpupig,  telling  it  to  display  back  on  the  local  workstation. 

Below  is  a sample  ocinitrc  that  starts  a clock,  several  terminals,  and  leaves  the  window  manager 
running  as  the  “last”  application.  Assuming  that  the  window  manager  has  been  configured 
properly,  the  user  then  chooses  the  Exit  menu  item  to  shut  down  X. 

xrdb  -load  $HOME/.Xres 
xsetroot  -solid  gray  & 
xclock  -g  50x50-0+0  -bw  0 & 
xload  -g  50x50-50+0  -bw  0 & 
xterm  -g  80x24+0+0  & 
xterm  -g  80x24+0-0  & 
twm 
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Sites  that  want  to  create  a common  startup  environment  could  simply  create  a default  jcinitrc 
that  references  a site-wide  startup  file: 

# ! /bin/sh 

. /usr/ local /lib/ site . xinit rc 

Another  approach  is  to  write  a script  that  starts  xinit  with  a specific  shell  script.  Such  scripts 
are  usually  named  xll,  xstart,  or  startx  and  are  a convenient  way  to  provide  a simple  interface 
for  novice  users: 

# ! /bin/ sh 

. /xinit/usr/local/bin/startx  — /usr/bin/Xll/Xhp  :1 


Environment  Variables 

XINITRC  Specifies  an  init  file  containing  shell  commands  to  start  up  the  initial  win- 
dows. By  default,  jcinitrc  in  the  home  directory  will  be  used. 

See  Also 

X,  Xserver,  xterm 

Author 

Bob  Scheifler,  MIT  Laboratory  for  Computer  Science. 
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Name 

xkill  - kill  a client  by  its  X resource. 

Syntax 

xkill  [options] 

Description 

xkill  is  a utility  for  forcing  the  X server  to  close  connections  to  clients.  This  program  is  very 
dangerous,  but  is  useful  for  aborting  programs  that  have  displayed  undesired  windows  on  a 
user’s  screen.  If  no  resource  identifier  is  given  with  -id,  xkill  will  display  a special  cursor  as  a 
prompt  for  the  user  to  select  a window  to  be  killed.  If  a pointer  button  is  pressed  over  a non- 
root window,  the  server  will  close  its  connection  to  the  client  that  created  the  window. 

Options 

-display  [Aost] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xkill  -display  your_node : 0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-id  resource 

Specifies  the  X identifier  for  the  resource  whose  creator  is  to  be  aborted.  If 
no  resource  is  specified,  xkill  will  display  a special  cursor  with  which  you 
should  select  a window  to  be  killed. 

-button  number 
-button  any 

Specifies  the  number  of  the  pointer  button  that  should  be  used  to  select  the 
window  to  kill.  If  the  word  any  is  specified,  any  button  on  the  pointer  can  be 
used.  By  default,  the  first  button  in  the  pointer  map  (which  is  usually  the  left- 
most button)  is  used. 

-all  Indicates  that  all  clients  with  top-level  windows  on  the  screen  should  be 

killed,  xkill  will  ask  you  to  select  the  root  window  with  each  of  the  currently 
defined  buttons  to  give  you  several  chances  to  abort.  Use  of  this  option  is 
highly  discouraged. 

-frame  Indicates  that  xkill  should  ignore  the  standard  conventions  for  finding  top- 

level  client  windows  (which  are  typically  nested  inside  a window  manager 
window),  and  simply  believe  that  you  want  to  kill  direct  children  of  the  root. 
(Available  as  of  Release  4.) 
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Resources 

Button  Specifies  a pointer  button  number  to  use  when  selecting  the  window  to  be 

removed.  If  the  word  any  is  specified,  any  button  on  the  pointer  can  be  used. 

See  Also 

X,  xwininfo;  Volume  One,  Xlib  Programming  Manual 

Author 

Jim  Fulton,  MIT  X Consortium; 

Dana  Chee,  Bellcore. 
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Name 

xload  - display  system  load  average. 

Syntax 

xload  [options] 


Description 

The  xload  program  displays  a periodically  updating  histogram  of  the  system  load  average. 

Options 

xload  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  listed  below: 


-scale  integer 

Specifies  the  minimum  number  of  tick  marks  in  the  histogram,  where  one 
division  represents  one  load  average  point.  If  the  load  goes  above  this  num- 
ber, xload  will  create  more  divisions,  but  it  will  never  use  fewer  than  this 
number.  The  default  is  1. 


-update  seconds 

Specifies  the  frequency  in  seconds  at  which  x load  updates  its  display.  If  the 
load  average  window  is  uncovered  (by  moving  windows  with  a window  man- 
ager or  by  the  x refresh  program),  the  graph  will  also  be  updated.  In  Release 
4,  the  minimum  amount  of  time  allowed  between  updates  is  1 second  (the 
default  is  5 seconds).  In  Release  3,  the  minimum  amount  of  time  allowed 
between  updates  is  5 seconds  (which  is  also  the  default). 


-hi  color  or 
-highlight  color 

Specifies  the  color  of  the  scale  lines  in  Release  4.  Specifies  the  color  of  the 
label  and  scale  lines  in  Release  3. 


-jumpscroll  pixels 

Specifies  the  number  of  pixels  to  shift  the  graph  to  the  left  when  the  graph 
reaches  the  right  edge  of  the  window.  The  default  value  is  1/2  the  width  of 
the  current  window.  Smooth  scrolling  can  be  achieved  by  setting  it  to  1. 
(Available  as  of  Release  4.) 

-label  string 

Specifies  the  text  string  for  the  label  above  the  load  average.  (Available  as  of 
Release  4.) 

-no label  Specifies  that  no  label  be  displayed  above  the  load  graph.  (Available  as  of 
Release  4.) 

The  following  standard  X Toolkit  options  are  commonly  used  with  xload: 

-bd  color  Specifies  the  border  color.  The  default  is  black. 

-bg  color  Specifies  the  background  color.  The  default  is  white. 
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-bw  pixels  Specifies  the  width  in  pixels  of  the  border  around  the  window.  The  default  is 

2. 

-f  g color  Specifies  the  graph  color.  The  default  is  black. 

-fn  fontname 

Specifies  the  font  to  be  used  in  displaying  the  name  of  the  host  whose  load  is 
being  monitored.  The  default  is  the  6x10  pixel,  fixed-width  font  “fixed”. 

-rv  Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 

and  background  colors. 

-geometry  geometry 

Specifies  the  size  and  location  of  the  window.  The  -geometry  option  can 
be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that 
begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
height+xoff+yoff. 

-display  [ host]:server[.screen ] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  create  the  xload 
window,  host  specifies  on  which  machine  to  create  the  xload  window, 
server  specifies  the  server  number,  and  screen  specifies  the  screen  num- 
ber. For  example, 

xload  -display  your_node: 0 . 1 

creates  an  xload  window  on  screen  1 of  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary 
in  all  cases. 

-xrm  resourcestring 

Specifies  a resource  string  to  be  used.  This  is  especially  useful  for  setting 
resources  that  do  not  have  separate  command  line  options. 

Resources  (Release  4) 

In  addition  to  the  resources  available  to  each  of  the  widgets  used  by  xload,  there  is  one  resource 
defined  by  the  application  itself. 

showLabel  (class  Boolean) 

If  False,  then  no  label  will  be  displayed. 

Widgets  (Release  4) 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  that  compose 
xload.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  the  widget  instance  name. 
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XLoad  xload 

Paned  paned 

Label  label 
StripChart  load 

Resources  (Release  3) 

The  Release  3 version  of  xload  uses  the  Load  widget  in  the  X Toolkit.  It  understands  all  of  the 
core  resource  names  and  classes  as  well  as: 

width  (class  Width) 

Specifies  the  width  of  the  load  average  graph. 

height  (class  Height) 

Specifies  the  height  of  the  load  average  graph. 

update  (class  Interval) 

Specifies  the  frequency  in  seconds  at  which  the  load  should  be  redisplayed, 
scale  (class  Scale) 

Specifies  the  initial  number  of  ticks  on  the  graph.  The  default  is  1. 
minScale  (class  Scale) 

Specifies  the  minimum  number  of  ticks  that  will  be  displayed.  The  default  is 

1. 

foreground  (class  Foreground) 

Specifies  the  color  for  the  graph.  Using  the  class  specifies  the  color  for  all 
things  that  normally  would  appear  in  the  foreground  color.  The  default  is 
black  since  the  core  default  for  background  is  white. 

highlight  (class  Foreground) 

Specifies  the  color  for  the  text  and  scale  lines.  The  default  is  the  same  as  for 
the  foreground  resource. 

label  (class  Label) 

Specifies  the  label  to  use  on  the  graph.  The  default  is  the  hostname, 
font  (class  Font) 

Specifies  the  font  to  be  used  for  the  label.  The  default  is  “fixed.” 

reverseVideo  (class  ReverseVideo) 

Specifies  that  the  foreground  and  background  colors  should  be  reversed. 


See  Also 

X,  xrdb,  mem(4),  Athena  StripChart  widget  (Release  4),  Athena  Load  widget  (Release  3) 

Diagnostics 

Unable  to  open  display  or  create  window.  Unable  to  open  /dev/kmem.  Unable  to  query  win- 
dow for  dimensions.  Various  X errors. 
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Bugs 

This  program  requires  the  ability  to  open  and  read  /devlkmem.  Sites  that  do  not  allow  general 
access  to  this  file  should  make  x load  belong  to  the  same  group  as  /devlkmem  and  turn  on  the  set 
group  id  permission  flag. 

Reading  /devlkmem  is  inherently  non-portable.  Therefore,  the  routine  used  to  read  it 
(get_load . c)  must  be  ported  to  each  new  operating  system. 

Border  color  has  to  be  explicitly  specified  when  reverse  video  is  used. 

Authors 

K.  Shane  Hartman  (MIT-LCS)  and  Stuart  A.  Malone  (MIT-LCS); 

with  features  added  by  Jim  Gettys  (MIT-Athena),  Bob  Scheifler  (MIT-LCS),  Tony  Della  Fera 
(MIT- Athena),  and  Chris  Peterson  (MIT-LCS). 
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Name 

xlogo  - X Window  System  logo. 


Synopsis 

xlogo  [options] 


Description 

The  xlogo  program  displays  the  X Window  System  logo.  This  program  is  nothing  more  than  a 
wrapper  around  the  undocumented  Athena  Logo  widget 


Options 

xlogo  accepts  all  of  the  standard  X Toolkit  command  line  options,  of  which  the  following  are 
commonly  used: 


-bg  color 

-bd  color 
-bw  pixels 
-fg  color 

-rv 


Specifies  the  color  to  use  for  the  background  of  the  window.  The  default  is 
white.  A correct  color  for  the  background  is  something  like  maroon. 


Specifies  the  color  to  use  for  the  border  of  the  window.  The  default  is  black. 

Specifies  the  width  in  pixels  of  the  border  surrounding  the  window. 

Specifies  the  color  to  use  for  displaying  the  logo.  The  default  is  black.  A 
correct  color  for  the  foreground  is  something  like  silver,  which  you  can 
approximate  with  a shade  of  grey. 

Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 
and  background  colors. 


-geometry 


The  xlogo  window  is  created  with  the  specified  size  and  location  determined 
by  the  supphed  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xo  ff±yoff. 


-display  [host]:server[.screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  create  the  xlogo 
window  (see  X).  host  specifies  on  which  machine  to  create  the  xlogo  win- 
dow, server  specifies  the  server  number,  and  screen  specifies  the  screen 
number.  For  example, 


xlogo  -display  your_node : 0 . 1 

creates  an  xlogo  window  on  screen  1 of  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary 
in  all  cases. 
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-xrm  resourcestring 

Specifies  a resource  string  to  be  used.  This  is  especially  useful  for  setting 
resources  that  do  not  have  separate  command  line  options. 


Resources 

This  program  uses  the  Logo  widget  in  the  Athena  widget  set.  It  understands  all  of  the  core 
resource  names  and  classes  as  well  as: 

width  (class  Width) 

Specifies  the  width  of  the  logo. 

height  (class  Height) 

Specifies  the  height  of  the  logo. 

foreground  (class  Foreground) 

Specifies  the  foreground  color  for  the  logo.  The  default  depends  on  whether 
reverseVideo  is  specified.  If  reverseVideo  is  specified,  the  default  is 
white;  otherwise,  the  default  is  black. 

reverseVideo  (class  ReverseVideo) 

Specifies  that  the  foreground  and  background  should  be  reversed. 


Widgets 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  that  compose 
xlogo.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  widget  instance  name. 

XLogo  xlogo 

Logo  xlogo 


Files 

lusrlliblXl  1 lapp-defaults/XLogo  - specifies  required  resources  (as  of  Release  4). 

See  Also 

X,  xrdb 

Authors 

Ollie  Jones  of  Apollo  Computer  and  Jim  Fulton  of  the  X Consortium  wrote  the  logo  graphics 
routine,  based  on  a graphic  design  by  Danny  Chong  and  Ross  Chapman  of  Apollo  Computer. 


396 


X Window  System  User’s  Guide 


— List  Interned  Atoms 


/ 


xlsatoms 


Name 

xlsatoms  - list  interned  atoms  defined  on  server. 

Syntax 

xlsatoms  [options] 

Description 

Available  as  of  Release  4,  xlsatoms  lists  the  interned  atoms.  By  default,  all  atoms  starting  from 
1 (the  lowest  atom  value  defined  by  the  protocol)  are  listed  until  unknown  atom  is  found.  If  an 
explicit  range  is  given,  xlsatoms  will  try  all  atoms  in  the  range,  regardless  of  whether  or  not  any 
are  undefined. 

Options 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xlsatoms  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-format  print f_st ring 

Specifies  a printf-style  string  used  to  list  each  atom  Cvalue,  name>  pair, 
printed  in  that  order  (val  ue  is  an  unsigned  long  and  name  is  a char  *).  xlsa- 
toms will  supply  a newline  at  the  end  of  each  line.  The  default  is  %ld\t%s. 

-range  [low]-[high] 

Specifies  the  range  of  atom  values  to  check.  If  1 ow  is  not  given,  a value  of  1 
assumed.  If  high  is  not  given,  xlsatoms  will  stop  at  the  first  undefined  atom 
at  or  above  low. 

-name  string 

Specifies  the  name  of  an  atom  to  list.  If  the  atom  does  not  exist,  a message 
will  be  printed  on  the  standard  error. 


See  Also 

X,  Xserver,  xprop 

Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xlsclients  - list  client  applications  running  on  a display. 

Syntax 

xlsclients  [options] 

Description 

Available  as  of  Release  4,  xlsclients  is  a utility  for  listing  information  about  the  client  applica- 
tions running  on  a display.  It  may  be  used  to  generate  scripts  representing  a snapshot  of  the  the 
user’s  current  session. 

Options 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xlsclients  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-a  Specifies  that  clients  on  all  screens  should  be  listed.  By  default,  only  those 

clients  on  the  default  screen  are  listed. 

-1  Requests  a long  listing  showing  the  window  name,  icon  name,  and  class  hints 

in  addition  to  the  machine  name  and  command  string  in  the  default  listing. 

-m  maxcmdl ength 

Specifies  the  maximum  number  of  characters  in  a command  to  list.  The 
default  is  1000. 


See  Also 

X,  xprop,  xwininfo 

Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xlsfonts  - list  available  fonts. 

Syntax 

xlsfonts  [options]  [-fn  pattern ] 

Description 

xlsfonts  lists  the  fonts  that  match  the  given  pattern.  The  wildcard  character  may  be  used 
to  match  any  sequence  of  characters  (including  none),  and  “?”  to  match  any  single  character.  If 
no  pattern  is  given,  is  assumed. 

The  and  “?”  characters  must  be  quoted  to  prevent  them  from  being  expanded  by  the  shell. 


Options 

-display  [host]:server[.screen] 

Allows  you  to  specify  the  host,  server  and  screen.  For  example. 


xlsfonts  -display  your_node: 0 . 1 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  are  necessary  in  all  cases. 

-fn  pattern  Indicates  that  only  fonts  matching  the  specified  pattern  be  listed. 


-1[1[1]] 

-1 


Indicates  that  medium,  long,  and  very  long  listings,  respectively,  should  be 
generated  for  each  font. 

Indicates  that  a long  listing  should  be  generated  for  each  font.  (Release  3) 


-m 


Indicates  that  long  listings  should  also  print  the  minimum  and  maximum 
bounds  of  each  font. 


-C 


Indicates  that  listings  should  use  multiple  columns.  This  is  the  same  as 
-n  0. 


-1 


Indicates  that  listings  should  use  a single  column.  This  is  the  same  as  -n  1. 


-w  width  Specifies  the  width  in  characters  that  should  be  used  in  figuring  out  how  many 
columns  to  print.  The  default  is  79. 

-n  columns  Specifies  the  number  of  columns  to  use  in  displaying  the  output.  By  default,  it 
will  attempt  to  fit  as  many  columns  of  font  names  into  the  number  of  charac- 
ters specified  by  -w  width. 


See  Also 

X,  Xserver,  xset,  xfd,  xfontsel 


Bugs 

Doing  xlsfonts  -1  can  tie  up  your  server  for  a very  long  time.  This  is  really  a bug  with 
single-threaded,  non-preemptable  servers,  not  with  this  program. 
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Author 

Mark  Lillibridge,  MIT  Project  Athena; 
Jim  Fulton,  MIT  X Consortium; 

Phil  Karlton,  SGI. 


400 


X Window  System  User’s  Guide 


— List  Window  Tree 


xlswins 


/ 


Name 

xlswins  - server  window  list  displayer  for  X. 

Syntax 

xlswins  [options]  [ window_id ] 

Description 

xlswins  lists  the  window  tree.  By  default,  the  root  window  is  used  as  the  starting  point, 
although  another  window  may  be  specified  using  the  window_id option. 

Options 

-display  [ host] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xlswins  -display  your_node: 0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-1  Indicates  that  a long  listing  should  be  generated  for  each  window.  This 

includes  a number  indicating  the  depth,  the  geometry  relative  to  the  parent  as 
well  as  the  location  relative  to  the  root  window. 

-format  radix 

Specifies  the  radix  to  use  when  printing  out  window  IDs.  Allowable  values 
are:  hex,  octal,  and  decimal.  The  default  is  hex. 

-indent  number 

Specifies  the  number  of  spaces  that  should  be  indented  for  each  level  in  the 
window  tree.  The  default  is  2. 

window_id  Specifies  that  the  starting  point  for  the  window  tree  listing  is  the  window 
window_id. 

See  Also 

X,  Xserver,  xwininfo,  xprop 

Bugs 

This  should  be  integrated  with  xwininfo  somehow. 

Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xmag  - magnify  parts  of  the  screen. 

Syntax 

xmag  [options] 

Description 

The  xmag  program  allows  you  to  magnify  portions  of  the  screen.  If  no  explicit  region  is  speci- 
fied, a square  centered  around  the  pointer  is  displayed  indicating  the  area  to  be  enlarged.  Once 
a region  has  been  selected,  a window  is  popped  up  showing  a blown  up  version  of  the  region  in 
which  each  pixel  in  the  source  image  is  represented  by  a small  square  of  the  same  color.  Press- 
ing Button  1 on  the  pointer  in  the  enlargement  window  pops  up  a small  window  displaying  the 
position,  number,  and  RGB  value  of  the  pixel  under  the  pointer  until  the  button  is  released. 
Pressing  the  space  bar  or  any  other  pointer  button  removes  the  enlarged  image  so  that  another 
region  may  be  selected.  Pressing  q,  Q,  or  Control-C  in  the  enlargement  window  exits  the  pro- 
gram. 

Options 

-display  host] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  use  for  both  reading  the 
screen  and  displaying  the  enlarged  version  of  the  image,  host  specifies  the 
machine,  server  specifies  the  server  number,  and  screen  specifies  the 
screen  number.  For  example, 

xmag  -display  your_node:  0 . 1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  enlargement  window  is  created  with  the  specified  size  and  location  deter- 
mined by  the  supplied  geometry  specification.  The  -geometry  option  can 
be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that 
begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 

By  default,  the  size  is  computed  from  the  size  of  the  source  region  and  the 
desired  magnification.  Therefore,  only  one  of  -source  size  and  -mag 
magf actor  options  may  be  specified  if  a window  size  is  given  with  the 
-geometry  option. 

-source  geometry 

This  option  specifies  the  size  and/or  location  of  the  source  region  on  the 
screen.  By  default,  a 64x64  square  centered  about  the  pointer  is  provided  for 
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the  user  to  select  an  area  of  the  screen.  The  size  of  the  source  is  used  with  the 
desired  magnification  to  compute  the  default  enlargement  window  size. 
Therefore,  only  one  of  -geometry  size  and  -mag  mag  factor  options 
may  be  specified  if  a source  size  is  given  with  this  option. 

-mag  magf actor 

This  option  specifies  an  integral  factor  by  which  the  source  region  should  be 
enlarged.  The  default  magnification  is  5.  This  is  used  with  the  size  of  the 
source  to  compute  the  default  enlargement  window  size.  Therefore,  only  one 
of  -geometry  size  and  -source  geom  options  may  be  specified  if  a 
magnification  factor  is  given  with  this  option. 

-bw  pixels  This  option  specifies  the  width  in  pixels  of  the  border  surrounding  the  enlarge- 
ment window. 

-bd  col  or  This  option  specifies  the  color  to  use  for  the  border  surrounding  the  enlarge- 
ment window. 

-bg  color_or _pixel_value 

This  option  specifies  the  name  of  the  color  to  be  used  as  the  background  of 
the  enlargement  window.  If  the  name  begins  with  a percent  size  (%),  it  is 
interpreted  to  be  an  absolute  pixel  value.  This  is  useful  when  displaying  large 
areas  since  pixels  that  are  the  same  color  as  the  background  do  not  need  to  be 
painted  in  the  enlargement.  The  default  is  to  use  the  BlackPixel  of  the 
screen. 

-fn  fontname 

This  option  specifies  the  name  of  a font  to  use  when  displaying  pixel  values 
(used  when  button  1 is  pressed  in  the  enlargement  window). 

-z  This  option  indicates  that  the  server  should  be  grabbed  during  the  dynamics 

and  the  call  to  XGet  Image.  This  is  useful  for  ensuring  that  clients  don’t 
change  their  state  as  a result  of  entering  or  leaving  them  with  the  pointer. 


Resources 

The  xmag  program  uses  the  following  X resources: 

geometry  (class  Geometry) 

Specifies  the  size  and/or  location  of  the  enlargement  window. 

source  (class  Source) 

Specifies  the  size  and/or  location  of  the  source  region  on  the  screen. 

magnification  (class  Magnification) 

Specifies  the  enlargement  factor. 

borderWidth  (class  BorderWidth) 

Specifies  the  border  width  in  pixels. 

borderColor  (class  BorderColor) 

Specifies  the  color  of  the  border. 
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background  (class  Background) 

Specifies  the  color  or  pixel  value  to  be  used  for  the  background  of  the 
enlargement  window. 

font  (class  Font) 

Specifies  the  name  of  the  font  to  use  when  displaying  pixel  values  when  the 
user  presses  button  1 in  the  enlargement  window. 


See  Also 

X,  xwd 

Bugs 

This  program  will  behave  strangely  on  displays  that  support  windows  of  different  depths. 

Because  the  window  size  equals  the  source  size  times  the  magnification,  you  only  need  to  spec- 
ify two  of  the  three  parameters.  This  can  be  confusing. 

Being  able  to  drag  the  pointer  around  and  see  a dynamic  display  would  be  very  nice. 

Another  possible  interface  would  be  for  the  user  to  drag  out  the  desired  area  to  be  enlarged. 

Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xman  - display  manual  pages. 

Syntax 

xman  [options] 

Description 

xman  is  a manual  page  browser.  The  default  size  of  the  initial  xman  window  is  small  so  that 
you  can  leave  it  running  throughout  your  entire  login  session.  In  the  initial  window  there  are 
three  options:  Help  will  pop  up  a window  with  on-line  help,  Quit  will  exit,  and  Manual  Page 
will  pop  up  a window  with  a manual  page  browser  in  it.  You  may  pop  up  more  than  one  man- 
ual page  browser  window  from  a single  execution  of  xman. 

For  further  information  on  using  xman  please  read  the  on-line  help  information.  The  rest  of  this 
manual  page  will  discuss  customization  of  xman. 

Customization  (Release  4) 

xman  allows  customization  of  both  the  directories  to  be  searched  for  manual  pages,  and  the 
name  that  each  directory  will  map  to  in  the  Sections  menu,  xman  determines  which  directories 
it  will  search  by  reading  the  MANPATH  environment  variable.  If  no  MANPATH  is  found  then 
the  directory  is  /usr/man  is  searched  on  POSIX  systems.  This  environment  is  expected  to  be  a 
colon-separated  list  of  directories  for  xman  to  search. 

setenv  MANPATH  /mit/kit/man : /usr/man 

By  default,  xman  will  search  each  of  the  following  directories  (in  each  of  the  directories  speci- 
fied in  the  users  MANPATH)  for  manual  pages.  If  manual  pages  exist  in  that  directory  then  they 
are  added  to  list  of  manual  pages  for  the  corresponding  menu  item.  A menu  item  is  only 
displayed  for  those  sections  that  actually  contain  manual  pages. 


Directory 

Section  Name 

manl 

(1)  User  Commands 

man2 

(2)  System  Calls 

man3 

(3)  Subroutines 

man4 

(4)  Devices 

man5 

(5)  File  Formats 

man6 

(6)  Games 

man7 

(7)  Miscellaneous 

man8 

(8)  Sys.  Administration 

manl 

(1)  Local 

mann 

(n)  New 

mano 

(o)  Old 

For  instance,  a user  has  three  directories  in  her  manual  path  and  each  contain  a directory  called 
man3.  All  these  manual  pages  will  appear  alphabetically  sorted  when  the  user  selects  the  menu 
item  called  (3)  Subroutines.  If  there  is  no  directory  called  mano  in  any  of  the  directories  in  her 
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MANPATH,  or  there  are  no  manual  pages  in  any  of  the  directories  called  mano,  then  no  menu 
item  will  be  displayed  for  the  section  called  (o)  Old. 

By  using  the  mandesc  file  a user  or  system  manager  is  able  to  more  closely  control  which  man- 
ual pages  will  appear  in  each  of  the  sections  represented  by  menu  items  in  the  Sections  menu. 
This  functionality  is  only  available  on  a section  by  section  basis,  and  individual  manual  pages 
may  not  be  handled  in  this  manner  (Although  generous  use  of  symbolic  links,  ln(  1),  will  allow 
almost  any  configuration  you  can  imagine). 

The  format  of  the  mandesc  file  is  a character  followed  by  a label.  The  character  determines 
which  of  the  sections  will  be  added  under  this  label.  For  instance  suppose  that  you  would  like 
to  create  an  extra  menu  item  that  contains  all  programmer  subroutines.  This  label  should  con- 
tain all  manual  pages  in  both  sections  two  and  three.  The  mandesc  file  would  look  like  this: 

2Programmer  Subroutines 
3Programmer  Subroutines 

This  will  add  a menu  item  to  the  Sections  menu  that  would  bring  up  a listing  of  all  manual 
pages  in  sections  two  and  three  of  the  UNIX  Programmer’s  Manual.  Since  the  label  names  are 
exactly  the  same  they  will  be  added  to  the  same  section.  Note,  however,  that  the  original  sec- 
tions still  exist. 

If  you  want  to  completely  ignore  the  default  sections  in  a manual  directory  then  add  the  line: 

no  default  sections 

anyw'here  in  your  mandesc  file.  This  keeps  xman  from  searching  the  default  manual  sections  in 
that  directory  only.  As  an  example,  suppose  you  want  to  do  the  same  thing  as  above,  but  you 
don’t  think  that  it  is  useful  to  have  the  System  Calls  or  Subroutines  sections  any  longer.  You 
would  need  to  duplicate  the  default  entries,  as  well  as  adding  your  new  one. 

no  default  sections 

1(1)  User  Commands 

2Programmer  Subroutines 

3Programmer  Subroutines 

4(4)  Devices 

5(5)  File  Formats 

6(6)  Games 

7(7)  Miscellaneous 

8(8)  Sys . Administration 

1(1)  Local 

n(n)  New 

o(o)  Old 

xman  will  read  any  section  that  is  of  the  form  man<character> , where  <character>  is 
an  upper  or  lower  case  letter  (they  are  treated  distinctly)  or  a numeral  (0-9).  Be  warned,  how- 
ever, that  man(  1)  and  catman( 8)  will  not  search  directories  that  are  non-standard. 

Customization  (Release  3) 

xman  accomodates  new  manual  sections  by  the  use  of  the  environment  variable  MANPATH  and 
by  directory  description  files  named  mandesc.  xman  will  search  each  directory  specified  in  the 
environment  variable  MANPATH  for  the  following  subdirectories  only:  manO,  manl,  ..., 
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man8,  manl  (local),  and  mann  (new).  (It  usually  ignores  the  information  in  manO  unless  there  is 
a mandesc  file  that  specifically  tells  it  not  to.)  These  subdirectories  should  contain  man  pages. 
Any  manual  section  can  be  renamed  by  an  optional  mandesc  file. 

As  an  example,  if  MANPATH  was  set  to  lusrlmandusrlsipblman  and  there  was  no  mandesc  file 
in  lusrlman,  xman  would  put  all  of  the  files  in  the  default  section  names  (e.g.,  manl  gets  a sec- 
tion name  of  local).  But  if  there  were  a mandesc  file  in  lusrlsipblman  which  contained  the  line 
ISIPB  Programs,  then  xman  would  put  all  files  in  the  manl  subdirectory  in  a new  section  called 
“SIPB  Programs.”  xman  will  search  the  mandesc  file  until  there  are  no  more  lines  of  informa- 
tion. This  flexibility  is  ideal  for  courses  that  have  their  own  manual  pages. 

xman  creates  temporary  files  in  /tmp  for  all  unformatted  man  pages  and  all  apropos  searches. 

Options 

xman  accepts  all  of  the  standard  X Toolkit  command  line  options,  as  well  as  the  following  addi- 
tional options: 

-helpfile  filename 

Specifies  a helpfile  to  use  other  than  the  default. 

-bothshown  Allows  both  the  manual  page  and  manual  directory  to  be  on  the  screen  at  the 
same  time. 

-notopbox  Starts  without  the  top  menu  with  the  three  buttons  in  it. 

-pagesize  geometry 

Sets  the  size  and  location  of  all  the  Manual  Pages. 

The  following  X Toolkit  options  are  commonly  used  with  xman: 

-geometry  geometry 

Sets  the  size  and  location  of  the  Top  Menu  with  the  three  buttons  in  it.  The 
top  menu  with  the  three  buttons  in  it  is  created  with  the  specified  size  and 
location  determined  by  the  supplied  geometry  specification.  The 
-geometry  option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a 
conflicting  option  that  begins  with  “g.”  The  argument  to  the  geometry  option 
( geometry ) is  referred  to  as  a “standard  geometry  string,”  and  has  the  form 
wi  dthxhei  gh  t±xoff±yoff. 

-display  [ host] : serverf . screen] 

Allows  you  to  specify  the  host,  server  and  screen  on  which  to  display  the 
xman  window,  host  specifies  the  machine,  server  specifies  the  server 
number,  and  screen  specifies  the  screen  number.  For  example, 

xman  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 
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-bw  pixels  or  -borderwidth  pixels 

Specifies  the  width  of  the  border  for  all  windows  in  xman. 

-bd  color  or  -bordercolor  color 

Specifies  the  color  of  the  borders  of  all  windows  in  xman. 

-fg  color  or  -foreground  color 

Specifies  the  foreground  color  to  be  used. 

-bg  color  or  -background  color 

Specifies  the  background  color  to  be  used. 

-fn  font  or  -font  font 

Specifies  the  font  to  use  for  all  buttons  and  labels. 

-name  name  Specifies  the  name  to  use  when  retrieving  resources. 

-title  ti  tie  Specifies  the  title  of  this  application. 

-xrm  resources 

Allows  a resource  to  be  specified  on  the  command  line. 

Resources  (Release  3 and  Release  4) 

The  resources  in  this  section  are  valid  for  both  Release  3 and  Release  4,  unless  otherwise 
indicated. 

The  xman  program  uses  the  following  X Toolkit  resources:  foreground,  background, 
width,  height,  borderwidth,  and  borderColor. 

In  addition,  xman  has  application-specific  resources  that  allow  unique  xman  customizations. 

manualFontNormal  (class  Font) 

The  font  to  use  for  normal  text  in  the  manual  pages. 

manualFontBold  (class  Font) 

The  font  to  use  for  bold  text  in  the  manual  pages. 

manualFontltalic  (class  Font) 

The  font  to  use  for  italic  text  in  the  manual  pages. 

directoryFontNormal  (class  Font) 

The  font  to  use  for  the  directory  text. 

bothShown  (class  Boolean) 

Either  true  or  false,  specifies  whether  or  not  you  want  both  the  directory  and 
the  manual  page  shown  at  start  up. 

directoryHeight  (class  DirectoryHeight) 

The  height  in  pixels  of  the  directory,  when  the  directory  and  the  manual  page 
are  shown  simultaneously. 

topCursor  (class  Cursor) 

The  cursor  to  use  in  the  top  box. 
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helpCursor  (class  Cursor) 

The  cursor  to  use  in  the  help  window. 

manpageCursor  (class  Cursor) 

The  cursor  to  use  in  the  manual  page  window. 

searchEntryCursor  (class  Cursor) 

The  cursor  to  use  in  the  search  entry  text  widget. 

pointerColor  (class  Foreground) 

The  color  of  all  the  cursors  (pointers)  listed  above.  The  name  was  chosen  to 
be  compatible  with  xterm.  (Available  as  of  Release  4.) 

helpFile  (class  File) 

Use  this  rather  than  the  system  default  helpfile. 

topBox  (class  Boolean) 

Either  true  or  false,  determines  whether  the  top  box  (containing  the  Help,  Quit 
and  Manual  Page  buttons)  or  a manual  page  is  put  on  the  screen  at  start-up. 
The  default  is  true. 

verticalList  (class  Boolean) 

Either  true  or  false,  determines  whether  the  directory  listing  is  vertically  or 
horizontally  organized.  The  default  is  horizontal  (false). 

Widgets  (Release  4) 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  the  widgets  that  compose 
xman.  In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class 
name  is  given  first,  followed  by  the  widget  instance  name. 

Xman  xman  (This  widget  is  never  used) 

TopLevelShell  topbox 
Form  form 

Label  topLabel 
Command  helpButton 
Command  quitButton 
Command  manpageButton 
TransientShell  search 

DialogWidgetClass  dialog 
Label  label 
Text  value 
Command  manualPage 
Command  apropos 
Command  cancel 
TransientShell  pleaseStandBy 
Label  label 

TopLevelShell  manualBrowser 
Paned  Manpage_Vpane 

Paned  horizPane 

MenuButton  options 
MenuButton  sections 
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Label  manualBrowser 
Viewport  directory 

List  directory 
List  directory 

. (one  for  each  section, 

. created  "on  the  fly") 

ScrollByLine  manualPage 
SimpleMenu  optionMenu 


SmeBSB 

displayDirectory 

SmeBSB 

displayManualPage 

SmeBSB 

help 

SmeBSB 

search 

SmeBSB 

showBothScreens 

SmeBSB 

removeThisManpage 

SmeBSB 

openNewManpage 

SmeBSB 

showVersion 

SmeBSB 

quit 

SimpleMenu  sectionMenu 

SmeBSB  <name  of  section> 

. (one  for  each  section) 

TransientShell  search 

DialogWidgetClass  dialog 
Label  label 
Text  value 
Command  manualPage 
Command  apropos 
Command  cancel 
TransientShell  pleaseStandBy 
Label  label 

TransientShell  likeToSave 
Dialog  dialog 

Label  label 
Text  value 
Command  yes 
Command  no 

TopLevelShell  help 

Paned  Manpage_Vpane 

Paned  horizPane 

MenuButton  options 
MenuButton  sections 
Label  manualBrowser 
ScrollByLine  manualPage 
SimpleMenu  optionMenu 

SmeBSB  displayDirectory 
SmeBSB  displayManualPage 
SmeBSB  help 
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SmeBSB 

search 

SmeBSB 

showBothScreens 

SmeBSB 

removeThisManpage 

SmeBSB 

openNewManpage 

SmeBSB 

showVersion 

SmeBSB 

quit 

Widgets  (Release  3) 

In  order  to  change  the  default  values  for  widget  resources  you  need  to  know  widget  names. 
Below  are  the  names  of  some  of  the  most  common  widgets.  You  can  also  reference  widgets  by 
class.  The  most  common  classes  are  Label,  Command,  and  Text. 

topBox  The  top  menu. 

help  The  help  window. 

manualBrowser 

The  manual  page  display  window. 

xmanCommands 

The  manual  page  command  popup  menu. 

xmanSections 

The  manual  page  section  popup  menu. 
xmanSearch  The  manual  page  search  popup  menu. 

Here  are  a few  examples  of  how  to  string  all  this  information  together  into  a resource  specifica- 
tion that  can  be  used  on  the  command  line  with  the  -xrm  flag,  or  added  to  an  X resources  or 
other  resource  file. 

xman*Command. foreground:  blue 

All  command  buttons  will  be  blue. 

xman*topBox*f oreground : blue 

Everything  in  the  top  menu  has  a blue  foreground. 

xman * Text .border : red 

All  text  widgets  have  a red  border. 

xman * Label . font : 9x15 

All  label  buttons  have  a 9x15  font. 

Global  Actions  (Release  4) 

xman  defines  all  user  interaction  through  global  actions.  This  allows  the  user  to  modify  the 
translation  table  of  any  widget,  and  bind  any  event  to  the  new  user  action.  The  list  of  actions 
supported  by  xman  are: 

GotoPage (page) 

When  used  in  a manual  page  display  window,  this  action  allows  the  user  to 
move  between  a directory  and  manual  page  display.  The  page  argument  can 
be  either  Directory  or  ManualPage. 
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Quit  ( ) Can  be  used  anywhere;  exits  xman. 

Search (type,  action) 

Only  useful  when  used  in  a search  popup,  this  action  will  cause  the  search 
widget  to  perform  the  named  search  type  on  the  string  in  the  search  popup’s 
value  widget.  This  action  will  also  pop  down  the  search  widget.  The  type 
argument  can  be  either  Apropos,  Manpage  or  Cancel.  If  an  action  of 
Open  is  specified  then  xman  will  open  a new  manual  page  to  display  the 
results  of  the  search,  otherwise  xman  will  attempt  to  display  the  results  in  the 
parent  of  the  search  popup. 

PopupHelp  ( ) Can  be  used  anywhere;  pops  up  the  help  widget. 

PopupSearch ( ) 

Can  be  used  anywhere,  except  in  a help  window.  It  will  cause  the  search 
popup  to  become  active  and  visible  on  the  screen,  allowing  the  user  search 
for  a manual  page. 

CreateNewManpage ( ) 

Can  be  used  anywhere;  creates  a new  manual  page  display  window. 
RemoveThisManpage  () 

Can  be  used  in  any  manual  page  or  help  display  window.  When  called  it  will 
remove  the  window,  and  clean  up  all  resources  associated  with  it. 

SaveFormattedPage  ( action ) 

Can  only  be  used  in  the  likeToSave  popup  widget,  and  tells  xman  whether 
to  Save  or  Cancel  a save  of  the  manual  page  that  has  just  been  formatted. 

ShowVersion ( ) 

May  be  called  from  any  manual  page  or  help  display  window,  and  will  cause 
the  informational  display  line  to  show  the  current  version  of  xman. 


Files 

<manpath  directory>/man<character> 

<manpath  directory>! cat<character> 

<manpath  directory>/mandesc 

lusr/lib/Xl  1 /app-defaults/Xman  - specifies  required  resources  (as  of  Release  4) 

/tmp  xman  creates  temporary  files  in  Ump  for  all  unformatted  man  pages  and  all  apropos 
searches. 

Environment  Variables 

MANPATH 

The  search  path  for  manual  pages.  Directories  are  separated  by  colons  (e.g., 
lusr/man  :/mit/kit/man:/foo/bar/man ). 

XAPPLRESDIR 

A string  that  will  have  “Xman”  appended  to  it.  This  string  will  be  the  full  path  name  of  a 
user  app-defaults  file  to  be  merged  into  the  resource  database  after  the  system  app-defaults 
file,  and  before  the  resources  that  are  attached  to  the  display.  (Available  as  of  Release  4.) 
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Bugs  in  Release  3 

The  -f  n and  -font  options  only  specify  the  fonts  for  the  command  button  and  not  the  text  of 
the  manpages  or  directories. 

Protocol  error  upon  selecting  Remove  This  Manpage. 

See  Also 

X,  apropos(l),  catman(8),  man(l),  Athena  Widget  set 

Authors 

Chris  Peterson,  MIT  X Consortium  from  the  V10  version  written  by  Barry  Shein  formerly  of 
Boston  University. 
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Name 

xmh  - X window  interface  to  the  mh  message  handling  system. 

Syntax 

xmh  [-path  mailpath ] [-initial  foldername]  [-flag]  [-toolki t option] 

Description 

This  reference  page  describes  the  Release  4 version  of  xmh,  a window-oriented  user  interface  to 
the  Rand  mh  Message  Handling  System.  The  Release  3 version  is  described  in  the  next  refer- 
ence page  in  this  guide. 

To  actually  do  things  with  your  mail,  xmh  makes  calls  to  the  mh  package.  Electronic  mail  mes- 
sages may  be  composed,  sent,  received,  replied  to,  forwarded,  sorted,  and  stored  in  folders. 

Please  don’t  be  misled  by  the  size  of  this  document.  It  introduces  many  aspects  of  the  Athena 
Widget  Set,  and  provides  extensive  mechanism  for  customization  of  the  user  interface,  xmh 
really  is  easy  to  use. 

Options 

xmh  accepts  all  of  the  standard  X Toolkit  command  line  options,  as  well  as  the  following: 
-path  mailpath 

To  specify  an  alternate  collection  of  mail  folders  in  which  to  process  mail, 
use  -path  followed  by  the  pathname  of  the  alternate  mail  directory.  The 
default  mail  path  is  the  value  of  the  Path  component  in  $HOME/.mh jprofile, 
or  $HOMElMail  if  the  MH  Path  is  not  given. 

-initial  foldername 

Specifies  an  alternate  folder  that  may  receive  new  mail  and  is  initially  opened 
by  xmh.  The  default  initial  folder  is  ‘inbox’. 

-flag  Causes  xmh  to  attempt  to  change  the  appearance  of  its  icon  when  new  mail 

arrives. 

These  three  options  have  corresponding  application-specific  resources,  named  MailPath, 
InitialFolder,  and  MailWaitingFlag,  which  can  be  used  in  a resource  file. 

See  X for  a list  of  the  standard  Toolkit  options. 

Installation 

The  current  version  of  xmh  requires  that  the  user  is  already  set  up  to  use  mh,  version  6.  To  do 
so,  see  if  there  is  a file  called  .mh _profile  in  your  home  directory.  If  it  exists,  check  to  see  if  it 
contains  a line  that  starts  with  Current-Folder.  If  it  does,  you’ve  been  using  version  4 or 
earlier  of  mh\  to  convert  to  version  6,  you  must  remove  that  line.  (Failure  to  do  so  causes  spuri- 
ous output  to  standard  error,  which  can  hang  xmh  depending  on  your  setup.) 

If  you  do  not  already  have  a .mh _profile,  you  can  create  one  (and  everything  else  you  need)  by 
typing  inc  to  the  shell.  You  should  do  this  before  using  xmh  to  incorporate  new  mail. 

For  more  information,  refer  to  the  mh(  1)  documentation. 
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Basic  Screen  Layout 

xmh  starts  out  with  a single  window,  divided  into  four  main  areas:  Six  buttons  with  pull-down 
command  menus.  A collection  of  buttons,  one  for  each  top  level  folder.  New  users  of  mh  will 
have  two  folders,  “drafts”  and  “inbox”.  A listing,  or  Table  of  Contents,  of  the  messages  in 
the  open  folder.  Initially,  this  will  show  the  messages  in  “inbox”.  A view  of  one  of  your  mes- 
sages. Initially  this  is  blank. 

xmh  and  the  Athena  Widget  Set 

xmh  uses  the  X Toolkit  Intrinsics  and  the  Athena  Widget  Set.  Many  of  the  features  described 
below  (scrollbars,  buttonboxes,  etc.)  are  actually  part  of  the  Athena  Widget  Set,  and  are 
described  here  only  for  completeness.  For  more  information,  see  the  Athena  Widget  Set  docu- 
mentation. 

Scrollbars 

Some  parts  of  the  main  window  will  have  a vertical  area  on  the  left  containing  a grey  bar.  This 
area  is  a scrollbar.  They  are  used  whenever  the  data  in  a window  takes  up  more  space  than  can 
be  displayed.  The  grey  bar  indicates  what  portion  of  your  data  is  visible.  Thus,  if  the  entire 
length  of  the  area  is  grey,  then  you  are  looking  at  all  your  data.  If  only  the  first  half  is  grey, 
then  you  are  looking  at  the  top  half  of  your  data.  The  message  viewing  area  will  have  a hori- 
zontal scrollbar  if  the  text  of  the  message  is  wider  than  the  viewing  area. 

You  can  use  the  pointer  in  the  scrollbar  to  change  what  part  of  the  data  is  visible.  If  you  click 
with  the  middle  button,  then  the  top  of  the  grey  area  will  move  to  where  the  pointer  is,  and  the 
corresponding  portion  of  data  will  be  displayed.  If  you  hold  down  the  middle  button,  you  can 
drag  around  the  grey  area.  This  makes  it  easy  to  get  to  the  top  of  the  data:  just  press  with  the 
middle,  drag  off  the  top  of  the  scrollbar,  and  release. 

If  you  click  with  button  1 , then  the  data  to  the  right  of  the  pointer  will  scroll  to  the  top  of  the 
window.  If  you  click  with  pointer  button  3,  then  the  data  at  the  top  of  the  window  will  scroll 
down  to  where  the  pointer  is. 

Buttonboxes,  Buttons,  and  Menus 

Any  area  containing  many  words  or  short  phrases,  each  enclosed  in  a rectangle  or  rounded 
boundary,  is  called  a buttonbox.  Each  rectangle  or  rounded  area  is  actually  a button  that  you 
can  press  by  moving  the  pointer  onto  it  and  pressing  pointer  button  1.  If  a given  buttonbox  has 
more  buttons  in  it  than  can  fit,  it  will  be  displayed  with  a scrollbar,  so  you  can  always  scroll  to 
the  button  you  want. 

Some  buttons  have  pull-down  menus.  Pressing  the  pointer  button  while  the  pointer  is  over  one 
of  these  buttons  will  pull  down  a menu.  Holding  the  button  down  while  moving  the  pointer 
over  the  menu,  called  dragging  the  pointer,  will  highlight  each  selectable  item  on  the  menu  as 
the  pointer  passes  over  it.  To  select  an  item  in  the  menu,  release  the  pointer  button  while  the 
item  is  highlighted. 

Adjusting  the  Relative  Sizes  of  Areas 

If  you’re  not  satisfied  with  the  sizes  of  the  various  areas  of  the  main  window,  they  can  easily  be 
changed.  Near  the  right  edge  of  the  border  between  each  region  is  a black  box,  called  a grip. 
Simply  point  to  that  grip  with  the  pointer,  press  a pointer  button,  drag  up  or  down,  and  release. 
Exactly  what  happens  depends  on  which  pointer  button  you  press. 
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If  you  drag  with  the  middle  button,  then  only  that  border  will  move.  This  mode  is  simplest  to 
understand,  but  is  the  least  useful. 

If  you  drag  with  pointer  button  1,  then  you  are  adjusting  the  size  of  the  window  above,  xmh 
will  attempt  to  compensate  by  adjusting  some  window  below  it 

If  you  drag  with  pointer  button  3,  then  you  are  adjusting  the  size  of  the  window  below,  xmh 
will  attempt  to  compensate  by  adjusting  some  window  above  it. 

All  windows  have  a minimum  and  maximum  size;  you  will  never  be  allowed  to  move  a border 
past  the  point  where  it  would  make  a window  have  an  invalid  size. 

Processing  Your  Mall 

This  section  will  define  the  concepts  of  the  selected  folder,  current  folder,  selected  message(s), 
current  message,  selected  sequence,  and  current  sequence.  Each  xmh  command  is  introduced. 

For  use  in  customization,  action  procedures  corresponding  to  each  command  are  given;  these 
action  procedures  can  be  used  to  customize  the  user  interface,  particularly  the  keyboard  accel- 
erators and  the  functionality  of  the  buttons  in  the  optional  button  box  created  by  the  application 
resource  CommandButtonCount. 

Selected  Folder 

A folder  contains  a collection  of  mail  messages,  or  is  empty. 

The  selected  folder  is  whichever  foldemame  appears  in  the  bar  above  the  folder  buttons.  Note 
that  this  is  not  necessarily  the  same  folder  that  is  being  viewed.  To  change  the  selected  folder, 
just  press  on  the  desired  folder  button;  if  that  folder  has  subfolders,  select  a folder  from  the  pull 
down  menu. 

The  Table  of  Contents,  or  toe,  lists  the  messages  in  the  viewed  folder.  The  title  bar  above  the 
Table  of  Contents  displays  the  name  of  the  viewed  folder. 

The  toe  title  bar  also  displays  the  name  of  the  viewed  sequence  of  messages  within  the  viewed 
folder.  Every  folder  has  an  “all”  sequence,  which  contains  all  the  messages  in  the  folder,  and 
initially  the  toe  title  bar  will  show  “inbox:all”. 

Folder  Commands 

The  Folder  command  menu  contains  commands  of  a global  nature: 

Open  Folder  Displays  the  data  in  the  selected  folder.  Thus,  the  selected  folder  also 
becomes  the  viewed  folder.  The  action  procedure  corresponding  to  this  com- 
mand is  XmhOpenFolder  ( [ foldername ] ) . It  takes  an  optional  argu- 
ment as  the  name  of  a folder  to  select  and  open;  if  no  folder  is  specified,  the 
selected  folder  is  opened.  It  may  be  specified  as  part  of  an  event  translation 
from  a folder  menu  button  or  from  a folder  menu,  or  as  a binding  of  a key- 
board accelerator  to  any  widget  other  than  the  folder  menu  buttons  or  the 
folder  menus. 
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Open  Folder  in  New  Window 

Displays  the  selected  folder  in  an  additional  main  window.  Note,  however, 
that  you  may  not  reliably  display  the  same  folder  in  more  than  one  window  at 
a time,  although  xmh  will  not  prevent  you  from  trying.  The  corresponding 
action  is  XmhOpenFolderlnNewWindow  ( ) . 

Create  Folder  Creates  a new  folder.  You  will  be  prompted  for  a name  for  the  new  folder,  to 
enter  the  name,  move  the  pointer  to  the  blank  box  provided  and  type.  Sub- 
folders are  created  by  specifying  the  parent  folder,  a slash,  and  the  subfolder 
name.  For  example,  to  create  a folder  named  “xmh”  which  is  a subfolder  of 
an  existing  folder  named  “clients”,  type  “clients/xmh”.  Click  on  the  Okay 
button  when  finished,  or  just  press  Return;  click  on  Cancel  to  cancel  this 
operation.  The  action  corresponding  to  Create  Folder  is  XmhCreate- 
Folder ( ) . 


Delete  Folder  Destroys  the  selected  folder.  You  will  be  asked  to  confirm  this  action  (see 
“Confirmation  Windows”).  Destroying  a folder  will  also  destroy  any  subfold- 
ers of  that  folder.  The  corresponding  action  is  XmhDeleteFolder  ( ) . 

Close  Window  Exits  xmh,  after  first  confirming  that  you  won’t  lose  any  changes;  or,  if 
selected  from  any  additional  xmh  window,  simply  closes  that  window.  The 
corresponding  action  is  XmhClose  ( ) . 

Highlighted  and  Selected  Messages  and  the  Current  Message 

It  is  possible  to  highlight  a set  of  adjacent  messages  in  the  area  of  the  Table  of  Contents.  To 
highlight  a message,  click  on  it  with  pointer  button  1.  To  highlight  a range  of  messages,  click 
on  the  first  one  with  pointer  button  1 and  on  the  last  one  with  pointer  button  3;  or  press  pointer 
button  1,  drag,  and  release.  To  extend  a range  of  selected  messages,  use  pointer  button  3.  To 
highlight  all  messages  in  the  table  of  contents,  click  rapidly  three  times  with  pointer  button  1. 
To  cancel  any  selection  in  the  table  of  contents,  click  rapidly  twice. 


The  selected  messages  are  the  same  as  the  highlighted  messages,  if  any.  If  no  messages  are 
highlighted,  then  the  selected  messages  are  considered  the  same  as  the  current  message. 

The  current  message  is  indicated  by  a V next  to  the  message  number.  It  usually  corresponds 
to  the  message  currently  being  viewed.  When  a message  is  viewed,  the  title  bar  above  the  view 
will  identify  the  message. 


Table  of  Contents  Commands 

The  Table  of  Contents  command  menu  contains  commands  which  operate  on  the  open,  or 
viewed  folder. 


Incorporate  New  Mail 

Adds  any  new  mail  received  to  your  inbox  folder,  and  set  the  current  message 
to  be  the  first  new  message.  (This  command  is  selectable  only  if  “inbox”  is 
the  folder  being  viewed.)  The  corresponding  action  is  Xmhlncorporate- 
NewMail ( ) . 
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Commit  Changes 

Executes  all  deletions,  moves,  and  copies  that  have  been  marked  in  this 


Pack  Folder 

folder.  The  corresponding  action  is  XmhCommitChanges  ( ) . 

Renumbers  the  messages  in  this  folder  so  they  start  with  1 and  increment  by 
1.  The  corresponding  action  is  XmhPackFolder  ( ) . 

Sort  Folder 

Sorts  the  messages  in  this  folder  in  chronological  order.  As  a side  effect,  this 
also  packs  the  folder.  The  corresponding  action  is  XmhSort Folder  ( ) . 

Rescan  Folder 

Rebuilds  the  list  of  messages.  This  can  be  used  whenever  you  suspect  that 
xmh’s  idea  of  what  messages  you  have  is  wrong.  (In  particular,  this  is  neces- 
sary if  you  change  things  using  straight  mh  commands  without  using  xmh.) 

The  corresponding  action  is  XmhForceRescan  ( ) . 

Message  Commands 

The  Message  command  menu  contains  commands  that  operate  on  the  selected  message(s),  or  if 
there  are  no  selected  messages,  the  current  message. 

Compose  Message 

Composes  a new  message.  A new  window  will  be  brought  up  for  composi- 
tion; a description  of  it  is  given  in  the  Composition  Windows  section  below. 
This  command  does  not  affect  the  current  message.  The  corresponding  action 
is  XmhComposeMessage ( ) . 

View  Next  Message 

Views  the  first  selected  message.  If  no  messages  are  highlighted,  view  the 


View  Previous 

current  message.  If  current  message  is  already  being  viewed,  view  the  first 
unmarked  message  after  the  current  message.  The  corresponding  action  is 
XmhViewNextMessage ( ) . 

Views  the  last  selected  message.  If  no  messages  are  highlighted,  view  the 
current  message.  If  current  message  is  already  being  viewed,  view  the  first 
unmarked  message  before  the  current  message.  The  corresponding  action  is 
XmhViewPrevious ( ) . 

Mark  Deleted 

Marks  the  selected  messages  for  deletion.  If  no  messages  are  highlighted, 
then  this  mark  the  current  message  for  deletion  and  automatically  display  the 
next  unmarked  message.  The  corresponding  action  is  XmhMark- 
Deleted ( ) . 

Mark  Move 

Marks  the  selected  messages  to  be  moved  into  the  current  (selected)  folder. 
(If  the  current  folder  is  the  same  as  the  viewed  folder,  this  command  will  just 
beep.)  If  no  messages  are  highlighted,  this  will  mark  the  current  message  to 
be  moved  and  display  the  next  unmarked  message.  The  corresponding  action 
is  XmhMarkMove  ( ) . 

Mark  Copy 

Marks  the  selected  messages  to  be  copied  into  the  current  folder.  (If  the  cur- 
rent folder  is  the  same  as  the  viewed  folder,  this  command  will  just  beep.)  If 
no  messages  are  highlighted,  mark  the  current  message  to  be  copied.  The 
corresponding  action  is  XmhMarkCopy  ( ) . 
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Unmark  Removes  any  of  the  above  three  marks  from  the  selected  messages,  or  the 

current  message,  if  none  are  highlighted.  The  corresponding  action  is  Xmh- 
Unmark ( ) . 

View  in  New  Window 

Creates  a new  window  containing  only  a view  of  the  first  selected  message,  or 
the  current  message,  if  none  are  highlighted.  The  corresponding  action  is 
XmhViewInNewWindow ( ) . 

Creates  a composition  window  in  reply  to  the  first  selected  message,  or  the 
current  message,  if  none  are  highlighted.  The  corresponding  action  is  Xmh- 
Reply  () . 

Creates  a composition  window  whose  body  is  initialized  to  be  the  contents  of 
the  selected  messages,  or  the  current  message  if  none  are  highlighted.  The 
corresponding  action  is  XmhForward  ( ) . 

Use  as  Composition 

Creates  a composition  window  whose  body  is  initialized  to  be  the  contents  of 
the  first  selected  message,  or  the  current  message  if  none  are  selected.  Any 
changes  you  make  in  the  composition  will  be  saved  in  a new  message  in  the 
“drafts”  folder,  and  will  not  change  the  original  message.  However,  this 
command  was  designed  to  be  used  within  the  “drafts”  folder  to  compose 
message  drafts,  and  there  is  an  exception  to  this  rule.  If  the  message  to  be 
used  as  composition  was  selected  from  the  “drafts”  folder,  the  changes  will 
be  reflected  in  the  original  message  (see  “Composition  Windows”).  The 
action  procedure  corresponding  to  this  command  is  XmhUse- 
AsComposition ( ) . 

Print  Prints  the  selected  messages,  or  the  current  message  if  none  are  selected,  xmh 

normally  prints  by  invoking  the  enscript(  1)  command,  but  this  can  be  custom- 
ized with  the  application-specific  resource  PrintCommand.  The  action  pro- 
cedure corresponding  to  this  command  is  XmhPrint  ( ) . 

Sequence  Commands 

The  Sequence  command  menu  contains  commands  pertaining  to  message  sequences  (See 
“Message-Sequences”),  and  a list  of  the  message-sequences  defined  for  the  currently  viewed 
folder.  The  selected  message-sequence  is  indicated  by  a check  mark  in  its  entry  in  the  margin 
of  the  menu.  To  change  the  selected  message-sequence,  select  a new  message-sequence  from 
the  sequence  menu. 

Pick  Messages  Defines  a new  message-sequence.  The  corresponding  action  is  XmhPick- 
Messages  ( ) . 

The  following  menu  entries  will  be  sensitive  only  if  the  current  folder  has  any  message- 
sequences  other  than  the  “all”  message-sequence. 

Open  Sequence  Changes  the  viewed  sequence  to  be  the  same  as  the  selected  sequence.  The 
corresponding  action  is  XmhOpenSequence  ( ) . 


Reply 


Forward 
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Add  to  Sequence 

Adds  the  selected  messages  to  the  selected  sequence.  The  corresponding 
action  is  XmhAddToSequence  ( ) . 

Remove  from  Sequence 

Removes  the  selected  messages  from  the  selected  sequence.  The  correspond- 
ing action  is  XmhRemoveFromSequence  ( ) . 

Delete  Sequence 

Removes  the  selected  sequence  entirely.  The  messages  themselves  are  not 
affected;  they  simply  are  no  longer  grouped  together  to  define  a message- 
sequence.  The  corresponding  action  is  XmhDeleteSequence  ( ) . 

View  Commands 

Commands  in  the  View  menu  and  in  the  buttonboxes  of  view  windows  (which  result  from  the 
Message  command  View  in  New  Window)  correspond  in  functionality  to  commands  of  the  same 
name  in  the  Message  menu,  but  they  operate  on  the  viewed  message  rather  than  the  selected 
messages  or  current  message. 

Close  Window  When  the  viewed  message  is  in  a separate  view  window,  this  command  will 
close  the  view,  after  confirming  the  status  of  any  unsaved  edits.  The  corre- 
sponding action  procedure  is  XmhCloseView  ( ) . 

Reply  Creates  a composition  window  in  reply  to  the  viewed  message.  The  related 

action  procedure  is  XmhViewReply  ( ) . 

Forward  Creates  a composition  window  whose  body  is  initialized  to  be  the  contents  of 

the  viewed  message.  The  corresponding  action  is  XmhViewForward  ( ) . 

Use  As  Composition 

Creates  a composition  window  whose  body  is  initialized  to  be  the  contents  of 
the  viewed  message.  Any  changes  made  in  the  composition  window  will  be 
saved  in  a new  message  in  the  “drafts”  folder,  and  will  not  change  the  origi- 
nal message.  An  exception:  if  the  viewed  message  was  selected  from  the 
“drafts”  folder,  the  original  message  is  edited.  The  action  procedure  corre- 
sponding to  this  command  is  XmhViewUseAsComposition  ( ) . 

Enables  the  direct  editing  of  the  viewed  message.  The  action  procedure  is 
XmhEditView ( ) . 

This  command  is  insensitive  until  the  message  has  been  edited;  when 
activated,  edits  will  be  saved  to  the  original  message  in  the  view.  The  corre- 
sponding action  is  Xmh  Save  View  ( ) . 

Prints  the  viewed  message,  xmh  prints  by  invoking  the  enscript(  1)  command, 
but  this  can  be  customized  with  the  application-specific  resource  Print - 
Command.  The  corresponding  action  procedure  is  XmhPrintView  ( ) . 


Edit  Message 
Save  Message 

Print 


Options  Menu 

The  Options  menu  contains  one  entry. 


420 


X Window  System  User’s  Guide 


X Interface  to  mh  (Release  4) 


(continued) 


xmh 


Read  in  Reverse  When  selected,  a check  mark  appears  in  the  margin  of  this  menu  entry.  Read 
in  Reverse  will  switch  the  meaning  of  the  next  and  previous  messages,  and 
will  increment  in  the  opposite  direction.  This  is  useful  if  you  want  to  read 
your  messages  in  the  order  of  most  recent  first.  The  option  acts  as  a toggle; 
select  it  from  the  menu  a second  time  to  undo  the  effect.  The  check  mark 
appears  when  the  option  is  selected. 

Composition  Windows 

Aside  from  the  normal  text  editing  functions,  there  are  six  command  buttons  associated  with 
composition  windows: 

Close  Window  Closes  this  composition  window.  If  changes  have  been  made  since  the  most 
recent  Save  or  Send,  you  will  be  asked  to  confirm  losing  them.  The  corre- 
sponding action  is  XmhCloseView  ( ) . 

Send  Sends  this  composition.  The  corresponding  action  is  XmhSend  ( ) . 

New  Headers  Replaces  the  current  composition  with  an  empty  message.  If  changes  have 

been  made  since  the  most  recent  Send  or  Save,  you  will  be  asked  to  confirm 
losing  them.  The  corresponding  action  is  XmhResetCompose  ( ) . 

Compose  Message 

Brings  up  another  new  composition  window.  The  corresponding  action  is 
XmhComposeMessage ( ) . 

Save  Message  Saves  this  composition  in  your  drafts  folder.  Then  you  can  safely  close  the 
composition.  At  some  future  date,  you  can  continue  working  on  the  composi- 
tion by  opening  the  drafts  folder,  selecting  the  message,  and  using  the  Use  as 
Composition  command.  The  corresponding  action  is  XmhSave  ( ) . 

Insert  Inserts  a related  message  into  the  composition.  If  the  composition  window 

was  created  with  a Reply  command,  the  related  message  is  the  message  being 
replied  to,  otherwise  no  related  message  is  defined  and  this  button  is  insensi- 
tive. The  message  may  be  filtered  before  being  inserted;  see  Reply- 
Insert  Filter  under  “Application-specific  Resources”  for  more  informa- 
tion. The  corresponding  action  is  Xmh  Insert  ( ) . 

Accelerators 

Accelerators  are  shortcuts.  They  allow  you  to  invoke  commands  without  using  the  menus, 
either  from  the  keyboard  or  by  using  the  pointer. 

xmh  defines  pointer  accelerators  for  common  actions:  To  select  and  view  a message  with  a 
single  click,  use  pointer  button  2 on  the  message’s  entry  in  the  table  of  contents.  To  select  and 
open  a folder  or  a sequence  in  a single  action,  make  the  folder  or  sequence  selection  with 
pointer  button  2. 

To  mark  the  highlighted  messages  to  be  moved  in  a single  action,  or  current  message  if  none 
have  been  highlighted,  use  pointer  button  3 to  select  the  target  folder.  Similarly,  selecting  a 
sequence  with  pointer  button  3 will  add  the  highlighted  or  current  message(s)  to  that  sequence. 
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In  both  of  these  operations,  the  selected  folder  or  sequence  and  the  viewed  folder  or 
are  not  changed. 

xmh  defines  the  following  keyboard  accelerators  over  the  surface  of  the  main  window, 
the  view  area  while  editing  a message: 

Meta-I  Incorporate  new  mail. 

Meta-C  Commit  changes. 

Meta-R  Rescan  folder. 

Meta-P  Pack  folder. 

Meta-S  Sort  folder. 

Meta-space  View  next  message. 

Meta-c  Mark  copy. 

Meta-d  Mark  deleted. 

Meta-f  Forward  the  selected  or  current  message. 

Meta-m  Mark  move. 

Meta-n  View  next  message. 

Meta-p  View  previous  message. 

Meta-r  Reply  to  the  selected  or  current  message. 

Meta-u  Unmark. 

Control-V  Scroll  the  table  of  contents  forward. 

Meta-V  Scroll  the  table  of  contents  backward. 

Control-v  Scroll  the  view  forward. 

Meta-v  Scroll  the  view  backward. 


sequence 
except  in 


Text  Editing  Commands 

All  of  the  text  editing  commands  are  actually  defined  by  the  Text  widget  in  the  Athena  Widget 
Set.  The  commands  may  be  bound  to  different  keys  than  the  defaults  described  below  through 
the  X Toolkit  Intrinsics  key  re-binding  mechanisms.  See  the  X Toolkit  Intrinsics  and  the 
Athena  Widget  Set  documentation  for  more  details. 

Whenever  you  are  asked  to  enter  any  text,  you  will  be  using  a standard  text  editing  interface. 
Various  control  and  meta  keystroke  combinations  are  bound  to  a somewhat  Emacs-like  set  of 
commands.  In  addition,  the  pointer  buttons  may  be  used  to  select  a portion  of  text  or  to  move 
the  insertion  point  in  the  text  Pressing  pointer  button  1 causes  the  insertion  point  to  move  to 
the  pointer.  Double-clicking  button  1 selects  a word,  triple-clicking  selects  a line,  quadruple- 
clicking  selects  a paragraph,  and  clicking  rapidly  five  times  selects  everything.  Any  selection 
may  be  extended  in  either  direction  by  using  pointer  button  3. 

In  the  following,  a line  refers  to  one  displayed  row  of  characters  in  the  window.  A paragraph 
refers  to  the  text  between  carriage  returns.  Text  within  a paragraph  is  broken  into  lines  for 
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display  based  on  the  current  width  of  the  window.  When  a message  is  sent,  text  is  broken  into 
lines  based  upon  the  values  of  the  SendBreakWidth  and  SendWidth  application-specific 
resources. 

The  following  keystroke  combinations  are  defined: 


Control-a 

Move  to  the  beginning  of  the  current  line. 

Control-b 

Move  backward  one  character. 

Control-d 

Delete  the  next  character. 

Control-e 

Move  to  the  end  of  the  current  line. 

Control-f 

Move  forward  one  character. 

Control-g 

Multiply  reset. 

Control-h 

Delete  previous  character. 

Control-j 

Create  a new  paragraph  with  the  same  indentation  as  the  previous  one. 

Control-k 

Kill  the  rest  of  the  current  line. 

Control-1 

Refresh  window. 

Control-m 

New  paragraph. 

Control-n 

Move  down  to  the  next  line. 

Control-o 

Break  this  paragraph  into  two. 

Control-p 

Move  up  to  the  previous  line. 

Control-r 

Search/replace  backward. 

Control-s 

Search/replace  forward. 

Control-t 

Transpose  characters. 

Control-u 

Multiply  by  4. 

Control-v 

Move  down  to  the  next  screenful  of  text. 

Control-w 

Kill  the  selected  text. 

Control-y 

Insert  the  last  killed  text 

Control-z 

Scroll  the  text  up  one  line. 

Meta-B 

Move  backward  one  word. 

Meta-d 

Delete  the  next  word. 

Meta-D 

Kill  the  next  word. 

Meta-f 

Move  forward  one  word. 

Meta-h 

Delete  the  previous  word. 

Meta-H 

Kill  the  previous  word. 
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Meta-i  Insert  file. 

Meta-k  Kill  to  end  of  paragraph. 

Meta-q  Form  paragraph. 

Meta-v  Move  up  to  the  previous  screenful  of  text 

Meta-y  Insert  current  text  selection. 

Meta-z  Scroll  one  line  down. 

Meta-<  Move  to  the  beginning  of  the  file. 

Meta->  Move  to  the  end  of  the  file. 

Meta-]  Move  forward  one  paragraph. 

Meta-[  Move  backward  one  paragraph. 

Meta-Delete  Delete  previous  word. 

Meta-Shift  Delete  Kill  previous  word. 

Meta-Backspace  Delete  previous  word. 

Meta-Shift  Backspace 

Kill  previous  word. 

In  addition,  the  pointer  may  be  used  to  cut  and  paste  text: 


Button  1 Down 

Start  selection. 

Button  1 Motion 

Adjust  selection. 

Button  1 Up 

End  selection  (cut). 

Button  2 Down 

Insert  current  selection  (paste). 

Button  3 Down 

Extend  current  selection. 

Button  3 Motion 

Adjust  selection. 

Button  3 Up 

End  selection  (cut). 

Confirmation  Dialog  Boxes 

Whenever  you  press  a button  that  may  cause  you  to  lose  some  work  or  is  otherwise  dangerous, 
a popup  dialog  box  will  appear  asking  you  to  confirm  the  action.  This  window  will  contain  an 
Abort  or  No  button  and  a Confirm  or  Yes  button.  Pressing  the  No  button  cancels  the  operation, 
and  pressing  the  Yes  will  proceed  with  the  operation. 

Some  dialog  boxes  contain  messages  from  mh.  Clicking  on  the  message  field  will  cause  the 
dialog  box  to  resize  so  that  you  can  read  the  entire  message. 

Message-Sequences 

An  mh  message  sequence  is  just  a set  of  messages  associated  with  some  name.  They  are  local 
to  a particular  folder,  two  different  folders  can  have  sequences  with  the  same  name.  In  all  fold- 
ers, the  sequence  “all”  is  predefined;  it  consists  of  the  set  of  all  messages  in  that  folder.  As 
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many  as  nine  sequences  may  be  defined  for  each  folder,  including  the  predefined  “all” 
sequence.  (The  sequence  “cur”  is  also  usually  defined  for  every  folder,  it  consists  of  only  the 
current  message,  xmh  hides  “cur”  from  the  user,  instead  placing  a “+”  by  the  current  mes- 
sage. Also,  xmh  does  not  support  the  “unseen”  sequence,  so  that  one  is  also  hidden  from  the 
user.) 

The  message  sequences  for  a folder  (including  one  for  “all”)  are  displayed  in  the  Sequence 
menu,  below  the  sequence  commands.  The  table  of  contents  (also  known  as  the  “toe”)  is  at 
any  one  time  displaying  one  message  sequence.  This  is  called  the  “viewed  sequence”,  and  its 
name  will  be  displayed  in  the  toe  title  bar  just  after  the  folder  name.  Also,  at  any  time  one  of 
the  sequences  in  the  menu  will  have  a check  mark  next  to  it.  This  is  called  the  “selected 
sequence”.  Note  that  the  viewed  sequence  and  the  selected  sequence  are  not  necessarily  the 
same.  (This  all  pretty  much  corresponds  to  the  way  the  folders  work.) 

The  Open  Sequence,  Add  to  Sequence,  Remove  from  Sequence,  and  Delete  Sequence  com- 
mands are  active  only  if  the  viewed  folder  contains  message-sequences. 

Note  that  none  of  the  above  actually  affect  whether  a message  is  in  the  folder.  Remember  that 
a sequence  is  a set  of  messages  within  the  folder,  the  above  operations  just  affect  what  mes- 
sages are  in  that  set. 

To  create  a new  sequence,  select  the  Pick  menu  entry.  A new  window  will  appear,  with  lots  of 
places  to  enter  text.  Basically,  you  can  describe  the  sequence’s  initial  set  of  messages  based  on 
characteristics  of  the  message.  Thus,  you  can  define  a sequence  to  be  all  the  messages  that 
were  from  a particular  person,  or  with  a particular  subject,  and  so  on.  You  can  also  connect 
things  up  with  boolean  operators,  so  you  can  select  all  things  from  “weissman”  with  the  sub- 
ject “xmh”. 

Hopefully,  the  layout  is  fairly  obvious.  The  simplest  cases  are  the  easiest:  just  point  to  the 
proper  field  and  type.  If  you  enter  in  more  than  one  field,  it  will  only  select  messages  which 
match  all  non-empty  fields. 

The  more  complicated  cases  arise  when  you  want  things  that  match  one  field  or  another  one, 
but  not  necessarily  both.  That’s  what  all  the  “or”  buttons  are  for.  If  you  want  all  things  with 
the  subject  “xmh”  or  “xterm”,  just  press  the  “or”  button  next  to  the  “Subject:”  field. 
Another  box  will  appear  where  you  can  enter  another  subject. 

If  you  want  all  things  either  from  “weissman”  or  with  subject  “xmh”,  but  not  necessarily 
both,  select  the  “-Or-”  button.  This  will  essentially  double  the  size  of  the  form.  You  can  then 
enter  “weissman”  in  a from:  box  on  the  top  half,  and  “xmh”  in  a subject:  box  on  the  lower 
part. 

If  you  select  the  Skip  button,  then  only  those  messages  that  don't  match  the  fields  on  that  row 
are  included. 

Finally,  in  the  bottom  part  of  the  window  will  appear  several  more  boxes.  One  is  the  name  of 
the  sequence  you’re  defining.  (It  defaults  to  the  name  of  the  selected  sequence  when  Pick  was 
pressed,  or  to  “temp”  if  “all”  was  the  selected  sequence.)  Another  box  defines  which 
sequence  to  look  through  for  potential  members  of  this  sequence;  it  defaults  to  the  viewed 
sequence  when  Pick  was  pressed. 
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Two  more  boxes  define  a date  range;  only  messages  within  that  date  range  will  be  considered. 
These  dates  must  be  entered  in  822-style  format:  each  date  is  of  the  form  “dd  mmm  yy 
hh:mm:ss  zzz”,  where  dd  is  a one  or  two  digit  day  of  the  month,  mmm  is  the  three-letter  abbre- 
viation for  a month,  and  yy  is  a year.  The  remaining  fields  are  optional:  hh,  mm,  and  ss  specify 
a time  of  day,  and  zzz  selects  a time  zone.  Note  that  if  the  time  is  left  out,  it  defaults  to  mid- 
night; thus  if  you  select  a range  of  “7  nov  86”  - “8  nov  86”,  you  will  only  get  messages  from 
the  7th,  as  all  messages  on  the  8th  will  have  arrived  after  midnight. 

Date  field  specifies  which  date  field  in  the  header  to  look  at  for  this  date  range;  it  probably 
won’t  be  useful  to  anyone.  If  the  sequence  you’re  defining  already  exists,  you  can  optionally 
merge  the  old  set  with  the  new;  that’s  what  the  Yes  and  No  buttons  are  all  about.  Finally,  you 
can  OK  the  whole  thing,  or  Cancel  it. 

In  general,  most  people  will  rarely  use  these  features.  However,  it’s  nice  to  occasionally  use 
Pick  to  find  some  messages,  look  through  them,  and  then  hit  Delete  Sequence  to  put  things  back 
in  their  original  state. 

Widget  Hierarchy 

In  order  to  specify  resources,  it  is  useful  to  know  the  hierarchy  of  widgets  which  compose  xmh. 
In  the  notation  below,  indentation  indicates  hierarchical  structure.  The  widget  class  name  is 
given  first,  followed  by  the  widget  instance  name.  The  application  class  name  is  Xmh. 

The  hierarchy  of  the  main  toe  and  view  window  is  identical  for  additional  toe  and  view  win- 
dows, except  that  a topLevelShell  widget  is  inserted  in  the  hierarchy  between  the  applica- 
tion shell  and  the  Paned  widget. 

Xmh  xmh 

Paned  xmh 

SimpleMenu  folderMenu 


SmeBSB 

open 

SmeBSB 

openlnNew 

SmeBSB 

create 

SmeBSB 

delete 

SmeLine 

line 

SmeBSB 

close 

SimpleMenu  tocMenu 

SmeBSB 

inc 

SmeBSB 

commit 

SmeBSB 

pack 

SmeBSB 

sort 

SmeBSB 

rescan 

SimpleMenu  messageMenu 

SmeBSB 

compose 

SmeBSB 

next 

SmeBSB 

prev 

SmeBSB 

delete 

SmeBSB 

move 

SmeBSB 

copy 

SmeBSB 

unmark 

SmeBSB 

viewNew 
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SmeBSB 

reply 

SmeBSB 

forward 

SmeBSB 

useAsComp 

SmeBSB 

print 

SimpleMenu  sequenceMenu 

SmeBSB 

pick 

SmeBSB 

openSeq 

SmeBSB 

addToSeq 

SmeBSB 

removeFror 

SmeBSB 

deleteSeq 

SmeLine 

line 

SmeBSB 

all 

SimpleMenu  viewMenu 

SmeBSB 

reply 

SmeBSB 

forward 

SmeBSB 

useAsComp 

SmeBSB 

edit 

SmeBSB 

save 

SmeBSB 

print 

SimpleMenu  optionMenu 

SmeBSB 

reverse 

Viewport . Core 

menuBox . c; 

Box  menuBox 

MenuButton 


folderButton 
MenuButton  tocButton 
MenuButton  messageButton 
MenuButton  sequenceButton 
MenuButton  viewButton 
MenuButton  optionButton 


Grip  grip 

Label  folderTitlebar 
Grip  grip 

Viewport . Core  folders. clip 
Box  folders 

MenuButton  inbox 
MenuButton  drafts 

SimpleMenu  menu 

SmeBSB  <folder  name> 


Grip  grip 
Label  tocTitlebar 
Grip  grip 
Text  toe 

Scrollbar  vScrollbar 
Grip  grip 
Label  viewTitlebar 
Grip  grip 
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Text  view 

Scrollbar  vScrollbar 
Scrollbar  hScrollbar 

The  hierarchy  of  the  Create  Folder  popup  dialog  box: 

transient She 11  prompt 
Dialog  dialog 

Label  label 
Text  value 
Command  okay 
Command  cancel 


The  hierarchy  of  the  Notice  dialog  box,  which  reports  messages  from  mh: 

transientShell  notice 
Dialog  dialog 

Label  label 
Text  value 
Command  confirm 

The  hierarchy  of  the  Confirmation  dialog  box: 

transientShell  confirm 
Dialog  dialog 

Label  label 
Command  yes 
Command  no 

The  hierarchy  of  the  dialog  box  which  reports  errors: 

transientShell  error 
Dialog  dialog 

Label  label 
Command  OK 


The  hierarchy  of  the  composition  window: 


topLevelShell  xmh 
Paned  xmh 

Label  composeTitlebar 

Text  comp 

Viewport . Core  compButtons . clip 
Box  compButtons 

Command  close 
Command  send 
Command  reset 
Command  compose 
Command  save 
Command  insert 
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The  hierarchy  of  the  view  window: 


topLevelShell  xmh 
Paned  xmh 

Label  viewTitlebar 
Text  view 

Viewport . Core  viewButtons . clip 
Box  viewButtons 

Command  close 
Command  reply 
Command  forward 
Command  useAsComp 
Command  edit 
Command  save 
Command  print 


The  hierarchy  of  the  pick  window: 
( Unnamed  widgets  have  no  name.) 


topLevelShell  xmh 
Paned  xmh 

Label  pickTitlebar 
Viewport . core  pick. clip 
Form  form 
Form 

The  first  6 rows  of  the  pick  window  have  identical  structure: 

Form 

Toggle 

Toggle 

Label 

Text 

Command 


Form 


Form 


Viewport . core  pick. clip 
Form  form 
From 

Form 


Toggle 

Toggle 

Text 

Text 

Command 

Command 


Label 

Text 

Label 

Text 
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Form 

Label 

Text 

Label 

Text 

Label 

Text 

Form 

Label 

Toggle 

Toggle 

Form 

Command 

Command 


Application-specific  Resources 

Resource  instance  names  begin  with  a lower  case  letter  but  are  otherwise  identical  to  the  class 
name. 

If  TocGeometry,  ViewGeomet ry,  CompGeometry,  or  PickGeometry  are  not  speci- 
fied, then  the  value  of  Geometry  is  used  instead.  If  the  resulting  height  is  not  specified  (e.g., 
“=500”,  “+0-0”),  then  the  default  height  of  windows  is  calculated  from  fonts  and  line 
counts.  If  the  width  is  not  specified  (e.g.,  “=x300”,  “-0+0),  then  half  of  the  display  width  is 

used.  If  unspecified,  the  height  of  a pick  window  defaults  to  half  the  height  of  the  display. 

Any  of  these  options  may  also  be  specified  on  the  command  line  by  using  the  X Toolkit  Intrin- 
sics  resource  specification  mechanism.  Thus,  to  run  xmh  showing  all  message  headers, 

% xmh  -xrm  ' *Hid«BoringHeaders : off ' 

The  following  resources  are  defined: 

Banner  A short  string  that  is  the  default  label  of  the  folder,  Table  of  Contents,  and 

view.  The  default  is: 

xmh  MIT  X Consortium  R4 
BlockEventsOnBusy 

Whether  to  disallow  user  input  and  show  a busy  cursor  while  xmh  is  busy  pro- 
cessing a command.  Default  is  true. 

Busy  Cursor  The  name  of  the  symbol  used  to  represent  the  position  of  the  pointer, 
displayed  if  BlockEventsOnBusy  is  true,  when  xmh  is  processing  a time- 
consuming  command.  The  default  is  watch. 

BusyPointerColor 

The  foreground  color  of  the  busy  cursor.  Default  is  xtDefault- 
Foreground. 
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CheckFrequency 

How  often  to  check  for  new  mail,  make  checkpoints,  and  rescan  the  Table  of 
Contents,  in  minutes.  If  CheckNewMail  is  true,  xmh  checks  to  see  if  you 
have  new  mail  each  interval.  If  MakeCheckpoints  is  true,  checkpoints 
are  made  every  fifth  interval.  Also  every  fifth  interval,  the  Table  of  Contents 
is  checked  for  inconsistencies  with  the  file  system,  and  rescanned.  To  prevent 
all  of  these  checks  from  occurring,  set  CheckFrequency  to  0.  The  default 
is  1. 

CheckNewMail 

If  true,  xmh  will  check  at  regular  intervals  to  see  if  new  mail  has  arrived  for 
any  of  the  folders.  A visual  indication  will  be  given  if  new  mail  is  waiting  to 
be  retrieved.  Default  is  True.  (See  “Bugs”).  The  interval  can  be  adjusted 
with  the  CheckFrequency. 

CommandButtonCount 

The  number  of  command  buttons  to  create  in  a button  box  in  between  the  toe 
and  the  view  areas  of  the  main  window,  xmh  will  create  these  buttons  with 
the  names  buttonl,  button2  and  so  on,  in  a box  with  the  name 
commandBox.  The  user  can  specify  labels  and  actions  for  the  buttons  in  a 
private  resource  file;  see  the  section  on  “Actions”.  The  default  is  0. 

CompGeomet  ry 

Initial  geometry  for  windows  containing  compositions. 

Cursor  The  name  of  the  symbol  used  to  represent  the  pointer.  Default  is  lef  t_ptr. 

Draf tsFolder 

The  folder  used  for  message  drafts.  Default  is  drafts. 

Geometry  Default  geometry  to  use.  Default  is  none. 

HideBoringHeaders 

If  “on”,  then  xmh  will  attempt  to  skip  uninteresting  header  lines  within  mes- 
sages by  scrolling  them  off.  Default  is  on. 

InitialFolder 

Which  folder  to  display  on  startup.  Can  also  be  set  with  the  command-line 
option  -initial.  Default  is  inbox. 

InitiallncFile 

The  file  name  of  your  incoming  mail  drop,  xmh  tries  to  construct  a filename 
for  the  inc  -file  command,  but  in  some  installations  (e.g.,  those  using  the 
Post  Office  Protocol)  no  file  is  appropriate.  In  this  case,  InitiallncFile 
should  be  specified  as  the  empty  string,  and  inc  will  be  invoked  without  a 
-file  argument.  The  default  is  to  use  the  value  of  the  environment  variable 
MAIL,  or  if  that  is  not  set,  to  append  the  value  of  the  environment  variable 
USER  to  / usrl spool! mail! . 
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MailPath  The  full  path  prefix  for  locating  your  mail  folders.  May  also  be  set  with  the 
command-line  option,  -path.  The  default  is  the  Path  component  in 
$HOME/.mh _profile,  or  $HOMEIMail  if  none. 

MailWaitingFlag 

If  true,  xmh  will  attempt  to  set  an  indication  in  its  icon  when  new  mail  is 
waiting  to  be  retrieved.  If  this  option  is  true,  then  CheckNewMail  is  assumed 
to  be  true  as  well.  The  -flag  command  line  option  is  a quick  way  to  turn 
MailWaitingFlag  on. 

MakeCheckpoints 

If  true,  xmh  will  attempt  to  save  checkpoints  of  volatile  information.  The  fre- 
quency of  checkpointing  is  controlled  by  the  resource  CheckFrequency. 

MhPath  What  directory  in  which  to  find  the  mh  commands.  If  a command  isn’t  found 

here,  then  the  directories  in  the  user’s  path  are  searched.  Default  is 
lusrllocallmh6. 


PickGeometry 

Initial  geometry  for  pick  windows. 

PointerColor 

The  foreground  color  of  the  pointer.  Default  is  XtDef  aultForeground. 

P re  f ixWmAndlconName 

Whether  to  prefix  the  window  and  icon  name  with  “xmh:  “.  Default  is  true. 

Print Command 

What  sh  command  to  execute  to  print  a message.  Note  that  standard  output 
and  standard  error  must  be  specifically  redirected!  If  a message  or  range  of 
messages  is  selected  for  printing,  the  full  file  paths  of  each  message  file  is 
appended  to  the  specified  print  command.  The  default  is  “enscript  >/dev/null 
2>/dev/null”. 

Reply Insert Filter 

A shell  command  to  be  executed  when  the  Insert  button  is  activated  in  a com- 
position window.  The  full  path  and  filename  of  the  source  message  is  added 
to  the  end  of  the  command  before  being  passed  to  sh(  1).  The  default  filter  is 
cat ; i.e.,  it  inserts  the  entire  message  into  the  composition.  Interesting  filters 
are:  awk  -e  ’ {print  “ “ $0}  ’ or  <mh  directory>/lib/mhl  -form  mhl.body. 

ReverseReadOrder 

When  true,  the  next  message  will  be  the  message  prior  to  the  current  message 
in  the  table  of  contents,  and  the  previous  message  will  be  the  message  after 
the  current  message  in  the  table  of  contents.  The  default  is  false. 

SendBreakWidth 

When  a message  is  sent  from  xmh,  lines  longer  than  this  value  will  be  split 
into  multiple  lines,  each  of  which  is  no  longer  than  SendWidth.  This  value 
may  be  overridden  for  a single  message  by  inserting  an  additional  line  in  the 
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message  header  of  the  form  SendBreakwidth : value.  This  line  will  be 
removed  from  the  header  before  the  message  is  sent.  The  default  is  85. 

SendWidth  When  a message  is  sent  from  xmh,  lines  longer  than  SendBreakwidth 
characters  will  be  split  into  multiple  lines,  each  of  which  is  no  longer  than 
this  value.  This  value  may  be  overridden  for  a single  message  by  inserting  an 
additional  line  in  the  message  header  of  the  form  SendWidth : value. 
This  line  will  be  removed  from  the  header  before  the  message  is  sent.  The 
default  is  72. 


SkipCopied  Whether  to  skip  over  messages  marked  for  copying  when  using  View  Next 
Message  and  View  Previous  Message.  Default  is  true. 

SkipDeleted  Whether  to  skip  over  messages  marked  for  deletion  when  using  View  Next 
Message  and  View  Previous  Message.  Default  is  true. 

SkipMoved  Whether  to  skip  over  messages  marked  for  moving  to  other  folders  when 
using  View  Next  Message  and  View  Previous  Message.  Default  is  true. 


StickyMenu  If  true,  when  popup  command  menus  are  used,  the  most  recently  selected 
entry  will  be  under  the  cursor  when  the  menu  pops  up.  Default  is  false.  See 
the  file  clients! xmhtXmh .sample  for  an  example  of  how  to  specify  resources 
for  pop  up  command  menus. 

TempDir  Directory  for  xmh  to  store  temporary  directories.  For  privacy,  a user  might 

want  to  change  this  to  a private  directory.  Default  is  Itmp. 

TocGeometry  Initial  geometry  for  master  xmh  windows. 

TocPercentage 

The  percentage  of  the  main  window  that  is  used  to  display  the  Table  of  Con- 
tents. Default  is  33. 


TocWidth  How  many  characters  to  generate  for  each  message  in  a folder’s  table  of  con- 
tents. Default  is  100.  Use  80  if  you  plan  to  use  mhl  a lot,  because  it  will  be 
faster,  and  the  extra  20  characters  may  not  be  useful. 

ViewGeometry 

Initial  geometry  for  windows  showing  only  a view  of  a message. 


Actions 

Because  xmh  provides  action  procedures  which  correspond  to  command  functionality  and 
installs  accelerators,  users  can  customize  accelerators  in  a private  resource  file,  xmh  provides 
action  procedures  which  correspond  to  entries  in  the  command  menus;  these  are  given  in  the 
sections  describing  menu  commmands.  For  examples  of  specifying  customized  resources,  see 
the  file  clients! xmhIXmh. sample . Unpredictable  results  can  occur  if  actions  are  bound  to  events 
or  widgets  for  which  they  were  not  designed. 

In  addition  to  the  actions  corresponding  to  commands,  these  action  routines  are  defined: 
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XmhPushFolder ( [ foldername,  . . . ]) 

Pushes  each  of  its  argument(s)  onto  a stack  of  foldemames.  If  no  arguments 
are  given,  the  selected  folder  is  pushed  onto  the  stack. 

XmhPopFolder ( ) 

Pops  one  foldername  from  the  stack  and  sets  the  selected  folder. 
XmhPopupFolderMenu ( ) 

Should  always  be  taken  when  the  user  selects  a folder  button.  A folder  button 
represents  a folder  and  zero  or  more  subfolders.  The  menu  of  subfolders  is 
built  upon  the  first  reference,  by  this  routine.  If  there  are  no  subfolders,  this 
routine  will  mark  the  folder  as  having  no  subfolders,  and  no  menu  will  be 
built.  In  that  case  the  menu  button  emulates  a toggle  button.  When  subfold- 
ers exist,  the  menu  will  popup,  using  the  menu  button  action  PopupMenu  ( ) . 

XmhSetCurrentFolder ( ) 

Allows  menu  buttons  to  emulate  toggle  buttons  in  the  function  of  selecting  a 
folder.  This  action  is  for  menu  button  widgets  only,  and  sets  the  selected 
folder. 

XmhLeaveFolderButton ( ) 

Insures  that  the  menu  button  behaves  properly  when  the  user  moves  the 
pointer  out  of  the  menu  button  window. 

XmhPushSequence ( [sequencename,  . . . ]) 

Pushes  each  of  its  arguments  onto  the  stack  of  sequence  names.  If  no  argu- 
ments are  given,  the  selected  sequence  is  pushed  onto  the  stack. 

XmhPopSequence ( ) 

Pops  one  sequence  name  from  the  stack  of  sequence  names,  which  then 
becomes  the  selected  sequence. 

XmhPromptOkayAction ( ) 

Equivalent  to  pressing  the  okay  button  in  the  Create  Folder  popup. 

XmhCancelPick.  ( ) 

Equivalent  to  pressing  the  cancel  button  in  the  pick  window. 

Customization  Using  mh 

The  initial  text  displayed  in  a composition  window  is  generated  by  executing  the  corresponding 
mh  command;  i.e.,  comp,  repl,  or  forw,  and  therefore  message  components  may  be  customized 
as  specified  for  those  commands,  comp  is  executed  only  once  per  invocation  of  xmh  and  the 
message  template  is  re-used  for  each  successive  new  composition. 

Files 

'/Mail 

l.mh _projile  - mh  profile 
lusrllocallmh6  - mh  commands 
~/Mail/<folder>/.xmhcache  - scan  folder 
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IMaill  <folder>  / .mh_sequences  - sequence  definitions 
/tmp  - temporary  files 

See  Also 

X,  xrdb,  mh(l),  enscript(l);  Athena  Widget  Set;  Volume  Four,  X Toolkit  Intrinsics  Program- 
ming Manual’,  Volume  Five,  X Toolkit  Intrinsics  Reference  Manual 

Bugs 

Printing  support  is  minimal. 

Should  handle  the  “unseen”  message-sequence. 

Should  determine  by  itself  if  the  user  hasn’t  used  mh  before,  and  offer  to  create  the  .mh _profile, 
instead  of  hanging  on  inc. 

Still  a few  commands  missing  (rename  folder,  remail  message). 

A bug  in  mh  limits  the  the  number  of  characters  in  ,mh_sequences  to  BUFSIZ.  When  the  limit  is 
reached,  the  .mh  sequences  file  often  becomes  corrupted,  and  sequence  definitions  may  be  lost. 

Except  for  the  icon,  there  isn’t  an  indication  that  you  have  new  mail. 

There  should  be  a resource,  ShowOnlnc,  which  when  true,  would  show  the  current  message  in 
the  view  after  incorporating  new  mail. 

The  CheckFrequency  resource  should  be  split  into  two  separate  resources. 

WM_S  AVE_YOURSELF  protocol  is  ignored. 

WM_DELETE_WINDOW  protocol  doesn’t  work  right  when  requesting  deletion  of  the  first  toe 
and  view,  while  trying  to  keep  other  xmh  windows  around. 

Doesn’t  support  annotations  when  replying  to  messages. 

Copyright 

Copyright  1988, 1989,  Digital  Equipment  Corporation. 

Copyright  1989,  Massachusetts  Institute  of  Technology 
See  X for  a full  statement  of  rights  and  permissions. 

Author 

Terry  Weissman,  Digital  Western  Research  Laboratory; 

Modified  by  Donna  Converse,  MIT  X Consortium. 
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Name 

xmh  - X window  interface  to  the  mh  message  handling  system. 

Syntax 

xmh  [-path  mailpath ] [-initial  foldername ] [-flag]  [- toolkitoption ] 

Description 

This  reference  page  describes  the  Release  3 version  of  xmh , a window-oriented  user  interface  to 
the  mh  message  handling  system.  The  Release  4 version  is  described  on  the  preceding  refer- 
ence page  in  this  guide. 

xmh  consists  of  user-interface  code  only.  To  actually  do  things  with  your  mail,  it  makes  calls  to 
the  mh  package. 

Please  don’t  be  misled  by  the  size  of  this  document,  xmh  really  is  easy  to  use! 

Options 

xmh  accepts  all  of  the  standard  X Toolkit  command  line  options,  as  well  as  the  following: 
-path  mailpath 

To  specify  an  alternate  collection  of  mail  folders  in  which  to  process  mail, 
use  -path  followed  by  the  pathname  of  the  alternate  mail  directory.  The 
default  mail  path  is  the  value  of  the  Path  component  in  $HOME/.mh jjrofile, 
or  $HOME/Mail  if  the  MH  Path  is  not  given. 

-initial  foldername 

Specifies  an  alternate  folder  that  may  receive  new  mail  and  is  initially  opened 
by  xmh.  The  default  initial  folder  is  ‘inbox’. 

-flag  Causes  xmh  to  attempt  to  change  the  appearance  of  its  icon  when  new  mail 

arrives. 

These  three  options  have  corresponding  application-specific  resources,  named  MailPath, 
initialFolder,  and  MailWaitingFlag,  which  can  be  used  in  a resource  file. 

See  X for  a list  of  the  standard  Toolkit  options. 

installation 

The  current  version  of  xmh  requires  that  the  user  is  already  set  up  to  use  mh,  Version  6.  To  do 
so,  see  if  there  is  a file  called  .mh jjrofile  in  your  home  directory.  If  it  exists,  check  to  see  if  it 
contains  a line  that  starts  with  Current-Folder.  If  it  does,  then  you’ve  been  using  version 
4 or  earlier  of  mh\  to  convert  to  version  6,  you  must  remove  that  line.  (Failure  to  do  so  causes 
spurious  output  to  standard  error,  which  can  hang  xmh  depending  on  your  setup.) 

If  you  do  not  already  have  a .mh  jjrofile , you  can  create  one  (and  everything  else  you  need)  by 
typing  inc  to  the  shell. 

For  more  information,  refer  to  the  mh(  1)  documentation. 
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Running  xmh 

Run  xmh  as  you  would  any  other  X application  (e.g.,  xterm).  It  will  accept  a command-line  dis- 
play (of  the  form  -display  [host]:server[.  screen]  the  default  display  is  specified  in 
the  environment  variable  DISPLAY. 

The  rest  of  this  document  will  probably  be  rather  hard  to  follow  without  actually  running  xmh 
and  seeing  the  things  being  described. 

Basic  Screen  Layout 

xmh  starts  out  with  a single  screen.  There  will  be  6 or  7 areas  on  the  screen: 

• A list  of  your  folders.  (New  users  of  mh  will  see  only  “inbox”  here.) 

• A list  of  the  global  and  folder-oriented  commands. 

• A list  of  the  messages  in  one  of  your  folders  (initially,  this  will  show  the  messages  in 
“inbox”). 

• A list  of  the  message-oriented  commands. 

• A view  of  one  of  your  messages.  (Initially  this  is  blank.) 

• A list  of  commands  for  the  message  being  viewed. 

And,  there  will  possibly  be: 

• A list  of  message-sequences  defined  for  this  folder.  This  appears  just  below  the  list  of  mes- 
sages in  this  folder.  (Message-sequences  are  discussed  below;  if  you  don’t  know  what  they 
are,  then  you  won’t  have  any.) 

xmh  and  the  Toolkit 

xmh  uses  the  X Toolkit.  Many  of  the  features  described  below  (scrollbars,  buttonboxes,  etc.) 
are  actually  part  of  the  Toolkit,  and  are  described  here  only  for  completeness.  For  more  infor- 
mation, see  the  Toolkit  documentation. 

Scrollbars 

Some  parts  of  the  screen  will  have  a vertical  area  on  the  left  containing  a grey  bar.  This  area  is 
a scrollbar.  They  are  used  whenever  the  data  in  a window  takes  up  more  space  than  can  be 
displayed.  The  grey  bar  indicates  what  portion  of  your  data  is  visible.  Thus,  if  the  entire  length 
of  the  area  is  grey,  then  you  are  looking  at  all  your  data.  If  only  the  first  half  is  grey,  then  you 
are  looking  at  the  top  half  of  your  data. 

You  can  use  the  pointer  in  the  scrollbar  to  change  what  part  of  the  data  is  visible.  If  you  click 
with  the  middle  button,  then  the  top  of  the  grey  area  will  move  to  where  the  pointer  is,  and  the 
corresponding  portion  of  data  will  be  displayed.  If  you  hold  down  the  middle  button,  you  can 
drag  around  the  grey  area.  This  makes  it  easy  to  get  to  the  top  of  the  data:  just  press  with  the 
middle,  drag  off  the  top  of  the  scrollbar,  and  release. 

If  you  click  with  button  1,  then  the  data  to  the  right  of  the  pointer  will  scroll  to  the  top  of  the 
window.  If  you  click  with  pointer  button  3,  then  the  data  at  the  top  of  the  window  will  scroll 
down  to  where  the  pointer  is. 
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Buttonboxes 

Any  area  consisting  of  many  words  or  short  phrases,  each  enclosed  in  a box,  is  called  a button- 
box.  Each  box  is  actually  a button  that  you  can  press  by  moving  the  pointer  onto  it  and  pressing 
pointer  button  1.  If  a given  buttonbox  has  more  buttons  in  it  than  can  fit,  it  will  be  displayed 
with  a scrollbar,  so  you  can  always  scroll  to  the  button  you  want. 

Adjusting  the  Relative  Sizes  of  Areas  on  the  Screen 

If  you’re  not  satisfied  with  the  size  of  the  various  areas  on  the  screen,  they  can  easily  be 
changed.  Near  the  right  edge  of  the  border  between  each  region  is  a black  box,  called  a grip. 
Simply  point  to  that  grip  with  the  pointer,  press  a pointer  button,  drag  up  or  down,  and  release. 
Exactly  what  happens  depends  on  which  pointer  button  you  press. 

If  you  drag  with  the  middle  button,  then  only  that  border  will  move.  This  mode  is  simplest  to 
understand,  but  is  probably  the  least  useful. 

If  you  drag  with  pointer  button  1,  then  you  are  adjusting  the  size  of  the  window  above,  xmh 
will  attempt  to  compensate  by  adjusting  some  window  below  it. 

If  you  drag  with  pointer  button  3,  then  you  are  adjusting  the  size  of  the  window  below,  xmh 
will  attempt  to  compensate  by  adjusting  some  window  above  it. 

All  windows  have  a mininum  and  maximum  size;  you  will  never  be  allowed  to  move  a border 
past  the  point  where  it  would  make  a window  have  an  invalid  size. 

Selected  Folder 

The  selected  folder  is  whichever  foldemame  is  highlighted  in  the  top  buttonbox.  Note  that  this 
is  not  necessarily  the  same  folder  that  is  being  viewed.  To  change  the  selected  folder,  just  press 
on  the  desired  folder  button. 

General  Commands  and  Folder  Commands 

The  second  buttonbox  contains  commands  of  a global  nature: 

Quit  XMH  Exits  xmh,  after  first  checking  that  you  won’t  lose  any  changes. 

Compose  Message 

Composes  a new  message.  A new  window  will  be  brought  up;  for  a descrip- 
tion of  it,  see  “Composition  Windows,”  below. 

Open  Folder  Displays  the  data  in  the  selected  folder.  Thus,  the  selected  folder  also 
becomes  the  viewed  folder. 

Open  Folder  in  New  Window 

Creates  a new  screen,  and  displays  the  selected  folder  in  that  screen.  Note, 
however,  that  you  may  not  display  the  same  folder  in  more  than  one  screen  at 
a time. 

Create  Folder  Creates  a new  folder.  You  will  be  prompted  for  a name  for  the  new  folder,  to 
enter  the  name,  point  the  pointer  at  the  blank  box  provided  and  type.  Hit  the 
Confirm  button  when  finished,  or  hit  Abort  to  cancel  this  operation. 
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Delete  Folder  Destroys  the  selected  folder.  You  will  be  asked  to  confirm  this  action  (see 
“Confirmation  Windows”). 


Highlighted  Messages,  Selected  Messages  and  the  Current  Message 

It  is  possible  to  highlight  a set  of  messages  in  the  list  of  messages  for  the  viewed  folder.  To 
highlight  a message,  just  click  on  it  with  pointer  button  1.  To  highlight  a range  of  messages, 
click  on  the  first  one  with  pointer  button  1 and  on  the  last  one  with  pointer  button  3. 

The  selected  messages  are  the  same  as  the  highlighted  messages,  if  any.  If  no  messages  are 
highlighted,  then  the  selected  messages  are  considered  the  same  as  the  current  message. 

The  current  message  is  indicated  by  a “+”  next  to  the  message  number.  It  usually  corresponds 
to  the  message  currently  being  viewed. 


Message  Commands 

The  third  buttonbox  (fourth  if  you  have  message-sequences  displayed)  contains  commands  to 
deal  with  messages: 


Incorporate  New  Mail 

Adds  any  new  mail  received  to  your  inbox  folder,  and  set  the  current  message 
to  be  the  first  new  message.  (This  button  is  selectable  only  if  “inbox”  is  the 
folder  being  viewed.) 

View  Next  Message 

Views  the  first  selected  message.  If  no  messages  are  highlighted,  view  the 
current  message.  If  current  message  is  already  being  viewed,  view  the  first 
unmarked  message  after  the  current  message. 

View  Previous  Message 

Views  the  last  selected  message.  If  no  messages  are  highlighted,  view  the 
current  message.  If  current  message  is  already  being  viewed,  view  the  first 
unmarked  message  before  the  current  message. 

Mark  Deleted  Marks  the  selected  messages  for  deletion.  If  no  messages  are  highlighted, 
then  this  will  automatically  display  the  next  unmarked  message. 


Mark  Move  Marks  the  selected  messages  to  be  moved  into  the  current  folder.  (If  the  cur- 
rent folder  is  the  same  as  the  viewed  folder,  this  command  will  just  beep.)  If 
no  messages  are  highlighted,  then  this  will  automatically  display  the  next 
unmarked  message. 

Mark  Copy  Marks  the  selected  messages  to  be  copied  into  the  current  folder.  (If  the  cur- 
rent folder  is  the  same  as  the  viewed  folder,  this  command  will  just  beep.) 


Unmark 


Removes  any  of  the  above  three  marks  from  the  selected  messages. 


View  in  New  Window 

Creates  a new  window  containing  only  a view  of  the  first  selected  message. 
Reply  Creates  a composition  window  in  reply  to  the  first  selected  message. 
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Forward  Creates  a composition  window  whose  body  is  initialized  to  be  the  contents  of 

the  selected  messages. 

Use  as  Composition 

Creates  a composition  window  whose  body  is  initialized  to  be  this  message. 
Note  that  any  changes  you  make  in  the  composition  will  also  be  saved  in  this 
message.  This  function  is  meant  to  be  used  with  the  “drafts”  folder.  (See 
“Composition  Windows.”) 

Commit  Changes 

Executes  any  deletions,  moves,  and  copies  that  have  been  marked  in  this 
folder. 


Print  Prints  the  selected  messages,  xmh  normally  prints  by  invoking  the  enscript 

command,  but  you  may  change  the  command  it  uses.  (See  “Resources” 
below). 

Pack  folder  Renumbers  the  messages  in  this  folder  so  they  start  with  1 and  increment  by 

1. 


Sort  folder  Sorts  the  messages  in  this  folder  in  chronological  order.  As  a side  effect,  this 
also  packs  the  folder. 

Force  Rescan  Rebuilds  the  list  of  messages.  This  can  be  used  whenever  you  suspect  xmh's 
idea  of  what  messages  you  have  is  wrong.  (In  particular,  this  is  useful  if  you 
ever  change  things  using  straight  mh  commands  without  using  xmh.) 

Pick  Messages  Defines  a new  message-sequence.  (See  “Message-Sequences.”) 

The  following  buttons  will  appear  but  will  be  sensitive  only  if  the  current  folder  has  any  mes- 
sage-sequences defined.  (See  “Message-Sequences.”) 


Open  Sequence  Changes  the  viewed  sequence  to  be  the  same  as  the  selected  sequence. 


Add  to  Sequence 

Adds  the  selected  messages  to  the  selected  sequence. 


Remove  from  Sequence 

Removes  the  selected  messages  from  the  selected  sequence. 

Delete  Sequence 

Removes  the  selected  sequence  entirely.  Note  the  messages  themselves  are 
not  affected;  they  simply  are  no  longer  grouped  together  as  a message- 
sequence. 


View  Windows 

The  commands  in  these  windows  are  the  same  as  the  message  commands  by  the  same  name, 
except  instead  of  affecting  the  selected  messages,  they  affect  the  viewed  message.  In  addition 
there  is  the  Edit  View  button,  which  allows  you  to  edit  the  message  being  viewed.  While  edit- 
ing, the  Edit  View  button  will  change  to  a Save  View  button,  which  should  be  pressed  to  save 
your  edits. 
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Composition  Windows 

Aside  from  the  normal  text  editing  functions,  there  are  six  command  buttons  associated  with 
composition  windows: 


Close  Closes  this  composition  window.  If  changes  have  been  made  since  the  most 

recent  Save  or  Send,  you  will  be  asked  to  confirm  losing  them. 

Send  Sends  this  composition. 


Reset  Replaces  the  current  composition  with  an  empty  message.  If  changes  have 

been  made  since  the  most  recent  Send  or  Save,  you  will  be  asked  to  confirm 
losing  them. 

Compose  Brings  up  another  new  composition  window. 

Save  Saves  this  composition  in  your  drafts  folder.  (If  you  do  not  have  a folder 

named  “drafts”,  one  will  be  created.)  Then  you  can  safely  close  the  compo- 
sition. At  some  future  date,  you  can  continue  working  on  the  composition  by 
opening  your  drafts  folder,  selecting  the  message,  and  using  the  Use  as  Com- 
position command. 

Insert  Inserts  a related  message  into  the  composition.  If  the  composition  window 

was  created  with'a  Reply  button,  the  related  message  is  the  message  being 
replied  to,  otherwise  no  related  message  is  defined  and  this  button  is  inactive. 
The  message  will  be  filtered  before  being  inserted;  see  Replylnsert- 
Filter  under  “Resources”  below. 

Text  Editing  Commands 

All  of  the  text  editing  commands  are  actually  defined  by  the  Text  widget  in  the  X Toolkit.  The 
commands  may  be  bound  to  different  keys  than  the  defaults  described  below  through  the  stan- 
dard X Toolkit  key  re-binding  mechanisms.  See  the  X Toolkit  and  Athena  Widgets  documenta- 
tion for  more  details. 


Whenever  you  are  asked  to  enter  any  text,  you  will  be  using  a standard  text  editing  interface. 
Various  control  and  meta  keystroke  combinations  are  bound  to  a somewhat  Emacs-like  set  of 
commands.  In  addition,  the  pointer  buttons  may  be  used  to  select  a portion  of  text  or  to  move 
the  insertion  point  in  the  text.  Pressing  pointer  button  1 causes  the  insertion  point  to  move  to 
the  pointer.  Double-clicking  button  1 selects  a word,  triple-clicking  selects  a paragraph,  and 
quadruple-clicking  selects  everything.  Any  selection  may  be  extended  in  either  direction  by 
using  pointer  button  3. 

In  the  following,  a line  refers  to  one  displayed  row  of  characters  in  the  window.  A paragraph 
refers  to  the  text  between  carriage  returns.  Text  within  a paragraph  is  broken  into  lines  based 
on  the  current  width  of  the  window. 

The  following  keystroke  combinations  are  defined: 

Control-A  Move  to  the  beginning  of  the  current  line. 

Control-B,  Control-H,  Backspace 

Move  backward  one  character. 
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Control-D 

Delete  the  next  character. 

Control-E 

Move  to  the  end  of  the  current  line. 

Control-F  Move  forward  one  character. 

Control-J,  LineFeed 

Create  a new  paragraph  with  the  same  indentation  as  the  previous  one. 
Control-K  Kill  the  rest  of  this  line. 

Control-L  Refresh  window. 

Control-M,  Return 

New  paragraph. 


Control-N 

Move  down  to  the  next  line. 

Control-O 

Break  this  paragraph  into  two. 

Control-P 

Move  up  to  the  previous  line. 

Control-V 

Move  down  to  the  next  screenful  of  text. 

Control-W 

Kill  the  selected  text. 

Control-Y 

Insert  the  last  killed  text. 

Control-Z 

Scroll  the  text  one  line  up. 

Meta-< 

Move  to  the  beginning  of  the  document. 

Meta-> 

Move  to  the  end  of  the  document. 

Meta-[ 

Move  backward  one  paragraph. 

Meta-] 

Move  forward  one  paragraph. 

Meta-B 

Move  backward  one  word. 

Meta-D 

Kill  the  next  word. 

Meta-F  Move  forward  one  word. 

Meta-H,  Meta-Delete 

Kill  the  previous  word. 


Meta-I 

Insert  a file.  If  any  text  is  selected,  use  the  selected  text  as  the  filename. 
Otherwise,  a box  will  appear  in  which  you  can  type  the  desired  filename. 

Meta-V 

Move  up  to  the  previous  screenful  of  text. 

Meta-Y 

Stuff  the  last  selected  text  here.  Note  that  this  can  be  text  selected  in  some 
other  text  subwindow.  Also,  if  you  select  some  text  in  an  xterm  window,  it 
may  be  inserted  in  an  xmh  window  with  this  command.  Pressing  pointer  but- 
ton 2 is  equivalent  to  this. 

Meta-Z 

Scroll  the  text  one  line  down. 
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Delete  Delete  the  previous  character. 

Confirmation  Windows 

Whenever  you  press  a button  that  may  cause  you  to  lose  some  work  or  is  otherwise  dangerous, 
a window  will  appear  asking  you  to  confirm  the  action.  This  window  will  contain  an  Abort  or 
No  button  and  a Confirm  or  Yes  button.  Pressing  the  Abort  button  cancels  the  operation,  and 
pressing  the  “Confirm”  will  proceed  with  the  operation.  (A  very  handy  shortcut  exists:  if  you 
press  the  original,  offending  button  again,  it  will  be  interpreted  as  a Confirm.  If  you  press  any 
other  command  button,  it  will  be  interpreted  as  an  Abort.) 

Message-Sequences 

An  mh  message  sequence  is  just  a set  of  messages  associated  with  some  name.  They  are  local 
to  a particular  folder,  two  different  folders  can  have  sequences  with  the  same  name.  In  all  fold- 
ers, the  sequence  “all”  is  predefined;  it  consists  of  the  set  of  all  messages  in  that  folder.  (The 
sequence  “cur”  is  also  usually  defined  for  every  folder,  it  consists  of  only  the  current  message. 
xmh  hides  “cur”  from  the  user,  instead  placing  a “+”  by  the  current  message.  Also,  xmh  does 
not  support  the  “unseen”  sequence,  so  that  one  is  also  hidden  from  the  user.) 

The  message  sequences  for  a folder  are  displayed  as  buttons  containing  the  names  of  the 
sequences  (including  one  for  “all”).  The  table  of  contents  (aka  “toe”)  is  at  any  one  time  dis- 
playing one  message  sequence.  This  is  called  the  “viewed  sequence”;  if  it’s  not  “all”,  its 
name  will  be  displayed  in  the  title  bar  just  after  the  folder  name.  Also,  at  any  time  one  of  the 
sequence  buttons  will  be  highlighted.  This  is  called  the  “selected  sequence”.  Note  that  the 
viewed  sequence  and  the  selected  sequence  are  not  necessarily  the  same.  (This  all  pretty  much 
corresponds  to  the  way  the  folder  buttons  work.) 

The  Open  Sequence,  Add  to  Sequence,  Remove  from  Sequence,  and  Delete  Sequence  buttons 
are  active  only  if  the  viewed  folder  contains  message-sequences. 

Note  that  none  of  the  above  actually  effect  whether  a message  is  in  the  folder.  Remember  that 
a sequence  is  a set  of  messages  within  the  folder,  the  above  operations  just  affect  what  mes- 
sages are  in  that  set 

To  create  a new  sequence,  press  the  Pick  button.  A new  window  will  appear,  with  lots  of  places 
to  enter  text  Basically,  you  can  describe  the  sequence’s  initial  set  of  messages  based  on  charac- 
teristics of  the  message.  Thus,  you  can  define  a sequence  to  be  all  the  messages  that  were  from 
a particular  person,  or  with  a particular  subject,  and  so  on.  You  can  also  connect  things  up  with 
boolean  operators,  so  you  can  select  all  things  from  “weissman”  with  the  subject  “xmh”. 

Hopefully,  the  layout  is  fairly  obvious.  The  simplest  cases  are  the  easiest:  just  point  to  the 
proper  field  and  type.  If  you  enter  in  more  than  one  field,  it  will  only  select  messages  which 
match  all  non-empty  fields. 

The  more  complicated  cases  arise  when  you  want  things  that  match  one  field  or  another  one, 
but  not  necessarily  both.  That’s  what  all  the  “or”  buttons  are  for.  If  you  want  all  things  with 
the  subject  “xmh”  or  “xterm”,  just  press  the  “or”  button  next  to  the  “Subject:”  field. 
Another  box  will  appear  where  you  can  enter  another  subject. 
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If  you  want  all  things  either  from  “weissman”  or  with  subject  “xmh”,  but  not  necessarily 
both,  select  the  -Or-  button.  This  will  essentially  double  the  size  of  the  form.  You  can  then 
enter  “weissman”  in  a from:  box  on  the  top  half,  and  “xmh”  in  a subject:  box  on  the  lower 
part. 

If  you  ever  select  the  Skip  button,  then  only  those  messages  that  don't  match  the  fields  on  that 
row  are  included. 

Finally,  in  the  bottom  part  of  the  window  will  appear  several  more  boxes.  One  is  the  name  of 
the  sequence  you’re  defining.  (It  defaults  to  the  name  of  the  selected  sequence  when  Pick  was 
pressed,  or  to  “temp”  if  “all”  was  the  selected  sequence.)  Another  box  defines  which 
sequence  to  look  through  for  potential  members  of  this  sequence;  it  defaults  to  the  viewed 
sequence  when  Pick  was  pressed. 

Two  more  boxes  define  a date  range;  only  messages  within  that  date  range  will  be  considered. 
These  dates  must  be  entered  in  822-style  format:  each  date  is  of  the  form  “dd  mmm  yy 
hh:mm:ss  zzz”,  where  dd  is  a one  or  two  digit  day  of  the  month,  mmm  is  the  three-letter  abbre- 
viation for  a month,  and  yy  is  a year.  The  remaining  fields  are  optional:  hh,  mm,  and  ss  specify 
a time  of  day,  and  zzz  selects  a time  zone.  Note  that  if  the  time  is  left  out,  it  defaults  to  mid- 
night; thus  if  you  select  a range  of  “7  nov  86”  - “8  nov  86”,  you  will  only  get  messages  from 
the  7th,  as  all  messages  on  the  8th  will  have  arrived  after  midnight. 

Date  field  specifies  which  date  field  in  the  header  to  look  at  for  this  date  range;  it  probably 
won’t  be  useful  to  anyone.  If  the  sequence  you’re  defining  already  exists,  you  can  optionally 
merge  the  old  set  with  the  new;  that’s  what  the  Yes  and  No  buttons  are  all  about.  Finally,  you 
can  OK  the  whole  thing,  or  Cancel  it. 

In  general,  most  people  will  rarely  use  these  features.  However,  it’s  nice  to  occasionally  use 
Pick  to  find  some  messages,  look  through  them,  and  then  hit  Delete  Sequence  to  put  things  back 
in  their  original  state. 

Resources 

As  with  all  standard  X applications,  xmh  may  be  customized  through  entries  in  the  resource 
manager.  The  following  resource  manager  entries  are  defined:  [Note:  the  entry  names  must  be 
entered  in  either  all  lower-case,  or  in  the  exact  case  shown  below.] 

BackGround  Background  color.  Currently,  this  will  effect  only  buttons.  (Default  is  white.) 
ButtonFont  What  font  to  use  for  button  names.  (Default  is  timromlO.) 

CheckNewMail 

If  True,  xmh  will  check  at  regular  intervals  to  see  if  new  mail  has  arrived  for 
any  of  the  folders.  A visual  indication  will  be  given  if  new  mail  is  waiting  to 
be  retrieved.  (Default  is  true.) 

CompButtonLines 

How  many  rows  of  buttons  to  display  under  a composition.  (Default  is  1.) 
CompFont  What  font  to  use  when  composing  a message.  (Default  is  6x13.) 
CompGeometry 

Initial  geometry  for  windows  containing  compositions. 
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CompLines  How  many  lines  of  a composition  to  display.  (Default  is  20.) 

Conf  irmFont  What  font  to  use  for  confirmation  windows.  (Default  is  timromlOb.) 
FolderButtonLines 

How  many  rows  of  folder  command  buttons  to  display.  (Default  is  1.) 

FolderLines  How  many  rows  of  foldemame  buttons  to  display.  (Default  is  1.) 

ForeGround  Foreground  color.  Currently,  this  will  effect  only  title  bars  and  buttons. 
(Default  is  black.) 

Geometry  Default  geometry  to  use.  (Default  is  none.) 

HideBoringHeaders 

If  on,  then  xmh  will  attempt  to  skip  uninteresting  header  lines  within  mes- 
sages by  scrolling  them  off.  (Default  is  on.) 


InitialFolder 

Which  folder  to  display  on  startup.  May  also  be  set  with  the  command-line 
option  -initial.  (Default  is  inbox.) 


Initial IncFile 

The  filename  of  your  incoming  mail  drop,  xmh  tries  to  construct  a filename 
for  the  inc  -file  command,  but  in  some  installations  (e.g.,  those  using  the 
Post  Office  Protocol)  no  file  is  appropriate.  In  this  case,  initiallncFile 
should  be  specified  as  the  empty  string,  and  inc  will  be  invoked  without  a 
-file  argument. 

LabelFont  What  font  to  use  for  the  title  bars.  (Default  is  timrom  lOi.) 


MailPath  The  full  path  prefix  for  locating  your  mail  folders.  May  also  be  set  with  the 
command-line  option,  -path.  (Default  is  the  Path  component  in 
$HOME/.mh_profile,  or  $HOME/Mail  if  none.) 


MailWaitingFlag 

If  True,  xmh  will  attempt  to  set  an  indication  in  it’s  icon  when  new  mail  is 
waiting  to  be  retrieved.  If  this  option  is  True,  then  CheckNewMail  is 
assumed  to  be  True  as  well.  The  -flag  command  line  option  is  a quick  way 
to  turn  MailWaitingFlag  on. 

MhPath  What  directory  in  which  to  find  the  mh  commands.  If  a command  isn’t  found 

here,  then  the  directories  in  the  user’s  path  are  searched.  (Default  is 
Iusr/local/mh6 .) 


PickGeometry 

Initial  geometry  for  pick  windows. 

PickEnt ryFont 

What  font  to  use  for  user  text  fields  in  pick  windows.  (Default  is  timrom  10.) 


PickTextFont 

What  font  to  use  for  static  text  fields  in  pick  windows.  (Default  is  timrom  10.) 
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PrintCommand 

What  shell  command  to  execute  to  print  a message.  Note  that  standard  output 
and  standard  error  must  be  specifically  redirected!  If  a message  or  range  of 
messages  is  selected  for  printing,  the  full  file  paths  of  each  message  file  is 
appended  to  the  specified  print  command.  (Default  is  “enscript  >/dev/null 
2>  I dev  I null”). 

Reply Insert Filter 

A shell  command  to  be  executed  when  the  Insert  button  is  activated  in  a com- 
position window.  The  full  path  and  filename  of  the  source  message  is  added 
to  the  end  of  the  command  before  being  passed  to  sh(  1).  The  default  filter  is 
echo ; i.e.,  it  merely  inserts  the  name  of  the  file  into  the  composition.  Other 
interesting  filters  are  awk  -e  ’{print  ” “ $0}’  or  lusrlnewlmh.6.51  liblmhl 

- form  mhl.body. 

TempDir  Directory  for  xmh  to  store  temporary  directories.  For  privacy,  a user  might 
want  to  change  this  to  a private  directory.  (Default  is  Itmp.) 

TocButtonLines 

How  many  rows  of  message  command  buttons  to  display.  (Default  is  1.) 
TocFont  What  font  to  use  for  a folder’s  table  of  contents.  (Default  is  6x13.) 
TocGeometry  Initial  geometry  for  master  xmh  windows. 

TocLines  How  many  messages  to  display  in  a folder’s  table  of  contents.  (Default  is 

10.) 

TocWidth  How  many  characters  to  generate  for  each  message  in  a folder’s  table  of  con- 
tents. (Default  is  100.  Use  80  if  you  plan  to  use  mhl  a lot.) 

ViewButtonLines 

How  many  rows  of  buttons  to  display  under  a view  of  a message.  (Default  is 

1.) 

viewFont  What  font  to  use  for  a view  of  a message.  (Default  is  6x13.) 

ViewGeomet  ry 

Initial  geometry  for  windows  showing  only  a view  of  a message. 

viewLines  How  many  lines  of  a message  to  display.  (Default  is  20.) 

If  TocGeometry,  ViewGeometry,  CompGeomet ry,  or  PickGeometry  are  not  speci- 
fied, then  the  value  of  Geometry  is  used  instead.  If  the  resulting  height  is  not  specified  (e.g., 
“=500”,  “+0-0”),  then  the  default  height  is  calculated  from  the  fonts  and  line  counts  speci- 
fied above.  If  the  width  is  not  specified  (e.g.,  “=x300”,  “-0+0”),  then  half  of  the  display 

width  is  used.  If  unspecified,  the  height  of  a pick  window  defaults  to  half  the  height  of  the  dis- 
play. 

Any  of  these  options  may  also  be  specified  on  the  command  line  by  using  the  standard  X 
Toolkit  resource  specification  mechanism.  Thus,  to  run  xmh  showing  all  message  headers, 

% xmh  -xrm  ' *HideBoringHeaders : of f ' 
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The  initial  text  displayed  in  a composition  window  is  generated  by  executing  the  corresponding 
mh  command;  i.e.,  comp , repl,  or  forw  and  therefore  message  components  may  be  customized 
as  specified  for  those  commands,  comp  is  executed  only  once  per  invocation  of  xmh  and  the 
message  template  is  re-used  for  each  successive  new  composition. 

Files 

'/Mail 

~/.mh  _ profile 

See  Also 

X,  xrdb,  mh  - the  mh  Message  Handler 

Bugs 

Printing  support  is  minimal. 

Keyboard  shortcuts  for  commands  would  be  nice. 

Should  handle  the  “unseen”  message-sequence. 

Should  determine  by  itself  if  the  user  hasn’t  used  mh  before,  and  offer  to  set  things  up  for  him 
or  her. 

Still  a few  commands  missing  (rename  folder,  remail  message). 

Needs  sub-folder  support. 

Copyright 

Copyright  1988,  Digital  Equipment  Corporation. 

See  X for  a full  statement  of  rights  and  permissions. 

Author 

Terry  Weissman,  Digital  Western  Research  Laboratory. 
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Keyboard  Modifier  Utility — 


Name 

xmodmap  - keyboard  and  pointer  modifier  utility. 

Syntax 

xmodmap  [options]  [ filename ] 

Description 

xmodmap  is  a utility  for  displaying  and  altering  the  X keyboard  modifier  map  and  keymap  table 
on  the  specified  server  and  host.  It  is  intended  to  be  run  from  a user’s  X startup  script  to  setup 
the  keyboard  according  to  personal  tastes. 

With  no  arguments,  xmodmap  displays  the  current  map. 

Options 

-display  [ host] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  use.  For  example, 

xmodmap  -display  your  node: 0 . 0 

specifies  the  screen  0 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 


-help 

-grammar 

-verbose 

-quiet 

-n 


Indicates  that  a brief  description  of  the  command  line  arguments  should  be 
printed  on  the  standard  error.  This  will  be  done  whenever  an  unhandled  argu- 
ment is  given  to  xmodmap. 

Indicates  that  a help  message  describing  the  expression  grammar  used  in  files 
and  with  -e  expressions  should  be  printed  on  the  standard  error. 

Indicates  that  xmodmap  should  print  logging  information  as  it  parses  its  input. 

Turns  off  the  verbose  logging.  This  is  the  default. 

Indicates  that  xmodmap  should  not  change  the  mappings,  but  should  display 
what  it  would  do,  like  make(  1)  does  when  given  this  option.  (Cannot  be  used 
with  expressions  to  change  the  pointer  mapping.) 

-e  expression 

Specifies  an  expression  to  be  executed.  Any  number  of  expressions  may  be 
specified  from  the  command  line. 

-pm  Indicates  that  the  current  modifier  map  should  be  printed  on  the  standard 

output. 

-pk  Indicates  that  the  current  keymap  table  should  be  printed  on  the  standard 

output. 

-pp  Indicates  that  the  current  pointer  map  should  be  printed  on  the  standard 

output. 
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A lone  dash  means  that  the  standard  input  should  be  used  as  the  input  file. 

The  filename  specifies  a file  containing  xmodmap  expressions  to  be  executed.  This  file  is 
usually  kept  in  the  user’s  home  directory  and  has  a name  like  xmodmaprc. 

For  compatibility  with  an  older  version,  xmodmap  also  accepts  the  following  obsolete  single 
letter  options: 

- [SLC12345] 

These  options  indicate  that  all  current  keys  for  the  Shift,  Lock,  Control,  or 
Mod  modifier  sets  should  be  removed  from  the  modifier  map.  These  are 
equivalent  to  clear  expressions. 

-[sic]  keysym 

These  options  specify  a keysym  to  be  removed  from  the  Shift,  Lock,  or  Con- 
trol modifier  sets.  These  are  equivalent  to  remove  expressions. 

+[slcl2345]  keysym 

These  options  specify  a keysym  to  be  added  to  the  Shift,  Lock,  or  Control 
modifier  sets.  These  are  equivalent  to  add  expressions. 

Expression  Grammar 

The  xmodmap  program  reads  a list  of  expressions  and  parses  them  all  before  attempting  to  exe- 
cute any  of  them.  This  makes  it  possible  to  refer  to  keysyms  that  are  being  redefined  in  a natu- 
ral way  without  having  to  worry  as  much  about  name  conflicts.  Allowable  expressions  include: 

keycode  NUMBER  = KEYSYMNAME  . . . 

The  list  of  keysyms  is  assigned  to  the  indicated  keycode  (which  may  be 
specified  in  decimal,  hex  or  octal  and  can  be  determined  by  running  the  xev 
program  in  the  examples  directory).  Usually  only  one  keysym  is  assigned  to 
a given  code. 

keysym  KEYSYMNAME  = KEYSYMNAME  . . . 

The  KEYSYMNAME  on  the  left  hand  side  is  looked  up  to  find  its  current  key- 
code  and  the  line  is  replaced  with  the  appropriate  keycode  expression. 
Note  that  if  you  have  the  same  keysym  bound  to  multiple  keys,  this  might  not 
work. 

Clear  MOD IFI ERNAME 

This  removes  all  entries  in  the  modifier  map  for  the  given  modifier,  where 
valid  name  are:  Shift,  Lock,  Control,  Modi,  Mod2,  Mod3,  Mod4  and  Mod5 
(case  does  not  matter  in  modifier  names,  although  it  does  matter  for  all  other 
names).  For  example,  “clear  Lock”  will  remove  any  keys  that  were  bound  to 
the  lock  modifier. 
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add  MODIFIERNAME  = KEYSYMNAME  . . . 

This  adds  the  given  keysyms  to  the  indicated  modifier  map.  The  keysym 
names  are  evaluated  after  all  input  expressions  are  read  to  make  it  easy  to 
write  expressions  to  swap  keys. 

remove  MODIFIERNAME  = KEYSYMNAME  . . . 

This  removes  the  given  keysyms  from  the  indicated  modifier  map.  Unlike 
add,  the  keysym  names  are  evaluated  as  the  line  is  read  in.  This  allows  you 
to  remove  keys  from  a modifier  without  having  to  worry  about  whether  or  not 
they  have  been  reassigned. 

pointer  = default 

This  sets  the  pointer  map  back  to  its  default  settings  (button  1 generates  a 
code  of  1,  button  2 generates  a 2,  etc.). 

pointer  = X Y Z 

This  sets  the  pointer  map  to  contain  the  button  codes  X,  Y and  z,  where  X,  Y 
and  z are  numbers.  The  list  always  starts  with  the  first  physical  button. 

Lines  that  begin  with  an  exclamation  mark  (!)  are  taken  as  comments. 

If  you  want  to  change  the  binding  of  a modifier  key,  you  must  also  remove  it  from  the  appropri- 
ate modifier  map. 

Examples 

Many  pointers  are  designed  such  that  the  first  button  is  pressed  using  the  index  finger  of  the 
right  hand.  People  who  are  left  handed  frequently  find  that  it  is  more  comfortable  to  reverse  the 
button  codes  that  get  generated  so  that  the  primary  button  is  pressed  using  the  index  finger  of 
the  left  hand.  This  could  be  done  on  a 3 button  pointer  as  follows: 

% xmodmap  -e  "pointer  =3  2 1" 

Many  editor  applications  support  the  notion  of  Meta  keys  (similar  to  Control  keys  except  that 
Meta  is  held  down  instead  of  Control).  However,  some  servers  do  not  have  a Meta  keysym  in 
the  default  keymap  table,  so  one  needs  to  be  added  by  hand.  The  following  command  will 
attach  Meta  to  the  Multi-language  key  (sometimes  labeled  Compose  Character).  It  also  takes 
advantage  of  the  fact  that  applications  that  need  a Meta  key  simply  need  to  get  the  keycode  and 
don’t  require  the  keysym  to  be  in  the  first  column  of  the  keymap  table.  This  means  that  appli- 
cations that  are  looking  for  a Multi_key  (including  the  default  modifier  map)  won’t  notice  any 
change. 

% keysym  Multi_key  = Multi_key  Meta_L 

One  of  the  more  simple,  yet  convenient,  uses  of  xmodmap  is  to  set  the  keyboard’s  “rubout”  key 
to  generate  an  alternate  keysym.  This  frequently  involves  exchanging  Backspace  with  Delete 
to  be  more  comfortable  to  the  user.  If  the  ttymodes  resource  in  xterm  is  set  as  well,  all  termi- 
nal emulator  windows  will  use  the  same  key  for  erasing  characters: 

% xmodmap  -a  "keysym  Backspace  = Delete" 

% echo  "XTerm*ttyModes : erase  ~ ?"  | xrdb  -merge 
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Some  keyboards  do  not  automatically  generate  less  than  and  greater  than  characters  when  the 
comma  and  period  keys  are  shifted.  This  can  be  remedied  with  xmodmap  by  resetting  the  bind- 
ings for  the  comma  and  period  with  the  following  scripts: 

I 

! make  shift-,  be  < and  shift-,  be  > 

! 

keysym  comma  = comma  less 
keysym  period  = period  greater 

One  of  the  more  irritating  differences  between  keyboards  is  the  location  of  the  Control  and 
Shift  Lock  keys.  A common  use  of  xmodmap  is  to  swap  these  two  keys  as  follows: 

I 

! Swap  Caps_Lock  and  Control_L 

I 

remove  Lock  = Caps_Lock 
remove  Control  = Control_L 
keysym  Control_L  = Caps_Lock 
keysym  Caps_Lock  = Control_L 
add  Lock  = Caps_Lock 
add  Control  = Control_L 

The  keycode  command  is  useful  for  assigning  the  same  keysym  to  multiple  keycodes. 
Although  unportable,  it  also  makes  possible  to  write  scripts  that  can  reset  the  keyboard  to  a 
known  state.  The  following  script  sets  the  backspace  key  to  generate  Delete  (as  shown  above), 
flushes  all  existing  caps  lock  bindings,  makes  the  CapsLock  key  a control  key,  makes  F5  gener- 
ate Escape,  and  makes  Break/Reset  be  a shift  lock. 

I 

! On  the  HP,  the  following  keycodes  have  key  caps  as  listed: 

I 

! 101  Backspace 

! 55  Caps 

! 14  Ctrl 

! 15  Break/Reset 

! 86  Stop 

! 89  F5 


keycode  101  = Delete 
keycode  55  = Control_R 
clear  Lock 

add  Control  = Control_R 
keycode  89  = Escape 
keycode  15  = Caps_Lock 
add  Lock  = Caps_Lock 
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See  Also 

X 

Bugs 

Every  time  a key  code  expression  is  evaluated,  the  server  generates  a MappingNotify 
event  on  every  client.  This  can  cause  some  thrashing.  All  of  the  changes  should  be  batched 
together  and  done  at  once.  Clients  that  receive  keyboard  input  and  ignore  MappingNotify 
events  will  not  notice  any  changes  made  to  keyboard  mappings. 

xmodmap  should  generate  add  and  remove  expressions  automatically  whenever  a keycode 
that  is  already  bound  to  a modifier  is  changed. 

There  should  be  a way  to  have  the  remove  expression  accept  keycodes  as  well  as  keysyms  for 
those  times  when  you  really  mess  up  your  mappings. 

Authors 

Rewritten  by  Jim  Fulton,  MIT  X Consortium,  from  an  earlier  version  by  David  Rosenthal  of 
Sun  Microsystems. 
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Name 

xpr  - print  an  X window  dump. 

Syntax 

xpr  [options]  [ filename ] 

Description 

xpr  takes  as  input  a window  dump  file  produced  by  xwd  and  formats  it  for  output  on  PostScript 
printers,  the  DEC  LN03  or  LA  100,  the  IBM  PP3812  page  printer,  or,  as  of  Release  4,  the  HP 
LaserJet  (or  other  PCL  printers),  or  the  HP  PaintJet.  If  you  do  not  give  a file  option,  standard 
input  is  used.  By  default,  xpr  prints  the  largest  possible  representation  of  the  window  on  the 
output  page.  Options  allow  you  to  add  headers  and  trailers,  specify  margins,  adjust  the  scale 
and  orientation,  and  append  multiple  window  dumps  to  a single  output  file.  Output  is  sent  to 
standard  output  unless  you  specify  -output  filename. 


Options 

-device  printer_device 

Specifies  the  device  on  which  the  file  is  to  be  printed.  Currently  the  follow- 
ing printers  are  supported: 


ln03 

Digital  LN03. 

lalOO 

Digital  LA  100. 

1 jet 

HP  LaserJet  series  and  other  monochrome  PCL  devices, 
such  as  ThinkJet,  QuietJet,  RuggedWriter,  HP2560  series, 
and  HP2930  series  printers.  (As  of  Release  4.) 

P jet 

HP  PaintJet  (color  mode).  (As  of  Release  4.) 

p jetxl 

HP  PaintJet  XL  Color  Graphics  Printer  (color  mode).  (As 
of  Release  4.) 

PP 

IBM  PP3812. 

ps 

PostScript  printer. 

The  default  printer,  for  historical  reasons,  is  the  LN03.  -device  lw  (Apple 
LaserWriter)  is  equivalent  to  -device  pp  and  is  provided  only  for  back- 
wards compatibility. 


-scale  scale 

Affects  the  size  of  the  window  on  the  page.  The  PostScript,  LN03,  and  HP 
printers  are  able  to  translate  each  bit  in  a window  pixel  map  into  a grid  of  a 
specified  size.  For  example,  each  bit  might  translate  into  a 3x3  grid.  This  is 
specified  by  -scale  3.  By  default,  a window  is  printed  with  the  largest 
scale  that  fits  onto  the  page  for  the  specified  orientation. 

-height  inches 

Specifies  the  maximum  height  of  the  page. 
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-width  inches 

Specifies  the  maximum  width  of  the  page. 

-left  inches 

Specifies  the  left  margin  in  inches.  Fractions  are  allowed.  By  default,  the 
window  is  centered  on  the  page. 

-top  inches  Specifies  the  top  margin  for  the  picture  in  inches.  Fractions  are  allowed.  By 
default,  the  window  is  centered  on  the  page. 

-header  header 

Specifies  a header  string  to  be  printed  above  the  window.  Default  is  no 
header. 

-trailer  trailer 

Specifies  a trailer  string  to  be  printed  below  the  window.  Default  is  no  trailer. 

-landscape  Prints  the  window  in  landscape  mode.  By  default,  a window  is  printed  such 
that  its  longest  side  follows  the  long  side  of  the  paper. 

-portrait  Prints  the  window  in  portrait  mode.  By  default,  a window  is  printed  such  that 
its  longest  side  follows  the  long  side  of  the  paper. 

- r v Reverses  the  foreground  and  background  colors. 

-compact  Compresses  white  pixels  on  PostScript  printers. 

-output  filename 

Specifies  an  output  filename.  If  this  option  is  not  specified,  standard  output  is 
used. 

-append  filename 

Specifies  a filename  previously  produced  by  xpr  to  which  the  window  con- 
tents are  to  be  appended. 

-noff  When  specified  in  conjunction  with  -append,  the  window  appears  on  the 

same  page  as  the  previous  window. 

-split  n Allows  you  to  split  a window  onto  several  pages.  This  might  be  necessary  for 
large  windows  that  would  otherwise  cause  the  printer  to  overload  and  print 
the  page  in  an  obscure  manner. 

-plane  number 

Specifies  which  bit  plane  to  use  in  an  image.  The  default  is  to  use  the  entire 
image  and  map  values  into  black  and  white  based  on  color  intensities. 
(Available  as  of  Release  4.) 

-gray  2 I 3 I 4 

Uses  a simple  2x2,  3x3,  or  4x4  gray  scale  conversion  on  a color  image,  rather 
than  mapping  to  strictly  black  and  white.  This  doubles,  triples,  or  quadruples 
the  effective  width  and  height  of  the  image.  (Available  as  of  Release  4.) 

-psfig  Suppress  translation  of  the  PostScript  picture  to  the  center  of  the  page. 

(Available  as  of  Release  4.) 
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-density  dpi  Indicates  what  dot-per-inch  density  should  be  used  by  the  HP  printer.  (Avail- 
able as  of  Release  4.) 

-cutoff  level 

Changes  the  intensity  level  where  colors  are  mapped  to  either  black  or  white 
for  monochrome  output  on  a LaserJet  printer.  (Available  as  of  Release  4.) 
The  level  is  expressed  as  percentage  of  full  brightness.  Fractions  are 
allowed.  (Available  as  of  Release  4.) 

-noposition  Causes  header,  trailer,  and  image  positioning  command  generation  to  be 
bypassed  for  LaserJet,  PaintJet  and  PaintJet  XL  printers.  (Available  as  of 
Release  4.) 


-gamma  correction 

Changes  the  intensity  of  the  colors  printed  by  PaintJet  XL  printer.  The  cor- 
rection is  a floating  point  value  in  the  range  0.00  to  3.00.  Consult  the 
operator’s  manual  to  determine  the  correct  value  for  the  specific  printer. 
(Available  as  of  Release  4.) 


-render  algorithm 

Allows  PaintJet  XL  printer  to  render  the  image  with  the  best  quality  versus 
performance  tradeoff.  Consult  the  operator’s  manual  to  determine  which 
algorithms  are  available.  (Available  as  of  Release  4.) 

-slide  Allows  overhead  transparencies  to  be  printed  using  the  PaintJet  and  PaintJet 

XL  printers.  (Available  as  of  Release  4.) 

Limitations 

The  current  version  of  xpr  can  generally  print  out  on  the  LN03  most  X windows  that  are  not 
larger  than  two-thirds  of  the  screen.  For  example,  it  will  be  able  to  print  out  a large  emacs  win- 
dow, but  it  will  usually  fail  when  trying  to  print  out  the  entire  screen.  The  LN03  has  memory 
limitations  that  can  cause  it  to  incorrectly  print  very  large  or  complex  windows.  The  two  most 
common  errors  encountered  are  “band  too  complex’’  and  “page  memory  exceeded.”  In  the 
first  case,  a window  may  have  a particular  band  (a  row  six  pixels  deep)  that  contains  too  many 
changes  (from  black  to  white  to  black).  This  will  cause  the  printer  to  drop  part  of  the  line  and 
possibly  parts  of  the  rest  of  the  page.  The  printer  will  flash  the  number  ‘ 1’  on  its  front  panel 
when  this  problem  occurs.  A possible  solution  to  this  problem  is  to  increase  the  scale  of  the 
picture,  or  to  split  the  picture  onto  two  or  more  pages.  The  second  problem,  “page  memory 
exceeded,”  will  occur  if  the  picture  contains  too  much  black,  or  if  the  picture  contains  complex 
half-tones  such  as  the  background  color  of  a display.  When  this  problem  occurs  the  printer  will 
automatically  split  the  picture  into  two  or  more  pages.  It  may  flash  the  number  ‘5’  on  its  from 
panel.  There  is  no  easy  solution  to  this  problem.  It  will  probably  be  necessary  to  either  cut  and 
paste,  or  rework  the  application  to  produce  a less  complex  picture. 


There  are  several  limitations  on  the  use  of  xpr  with  the  LA  100:  the  picture  will  always  be 
printed  in  portrait  mode,  there  is  no  scaling,  and  the  aspect  ratio  will  be  slightly  off. 

Support  for  PostScript  output  currently  cannot  handle  the  -append,  -noff  or  -split 
options. 
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The  -compact  option  is  only  supported  for  PostScript  output.  It  compresses  white  space  but 
not  black  space,  so  it  is  not  useful  for  reverse-video  windows. 

For  color  images,  should  map  directly  to  PostScript  image  support. 

HP  Printer  Specifics  (Release  4) 

If  no  -density  is  specified  on  the  command  line,  300  dots  per  inch  will  be  assumed  for  1 jet 
and  90  dots  per  inch  for  p jet.  Allowable  density  values  for  a LaserJet  printer  are  300,  150, 
100,  and  75  dots  per  inch.  Consult  the  operator’s  manual  to  determine  densities  supported  by 
other  printers. 

If  no  -scale  is  specified  the  image  will  be  expanded  to  fit  the  printable  page  area. 

The  default  printable  page  area  is  8x10.5  inches.  Other  paper  sizes  can  be  accommodated  using 
the  -height  and  -width  options. 

Note  that  a 1024x768  image  fits  the  default  printable  area  when  processed  at  100  dpi  with 
scale=l,  the  same  image  can  also  be  printed  using  300  dpi  with  scale=3  but  will  require  con- 
siderably more  data  be  transferred  to  the  printer. 

xpr  may  be  tailored  for  use  with  monochrome  PCL  printers  other  than  the  LaserJet.  To  print  on 
a ThinkJet  (HP2225A)  xpr  could  be  invoked  as: 

% xpr  -dansity  96  -width  6.667  filename 
or  for  black-and-white  output  to  a PaintJet: 

% xpr  -donaity  180  filename 

The  monochrome  intensity  of  a pixel  is  computed  as  0.30*R  + 0.59*G  + 0.1 1*B.  If  a pixel’s 
computed  intensity  is  less  than  the  -cutoff  level  it  will  print  as  white.  This  maps 
light-on-dark  display  images  to  black-on-white  hardcopy.  The  default  cutoff  intensity  is  50% 
of  full  brightness.  Example:  specifying  -cutoff  87.5  moves  the  white/black  intensity 
point  to  87.5%  of  full  brightness. 

A LaserJet  printer  must  be  configured  with  sufficient  memory  to  handle  the  image.  For  a full 
page  at  300  dots  per  inch  approximately  2MB  of  printer  memory  is  required. 

Color  images  are  produced  on  the  PaintJet  at  90  dots  per  inch.  The  PaintJet  is  limited  to  sixteen 
colors  from  its  330  color  palette  on  each  horizontal  print  line,  xpr  will  issue  a warning  message 
if  more  than  sixteen  colors  are  encountered  on  a line,  xpr  will  program  the  PaintJet  for  the  first 
sixteen  colors  encountered  on  each  line  and  use  the  nearest  matching  programmed  value  for 
other  colors  present  on  the  line. 

Specifying  the  -rv,  reverse  video,  option  for  the  PaintJet  will  cause  black  and  white  to  be 
interchanged  on  the  output  image.  No  other  colors  are  changed. 

Multiplane  images  must  be  recorded  by  xwd  in  ZPixmap  format.  Single  plane  (monochrome) 
images  may  be  in  either  XYPixmap  or  ZPixmap  format. 

Some  PCL  printers  do  not  recognize  image  positioning  commands.  Output  for  these  printers 
will  not  be  centered  on  the  page  and  header  and  trailer  strings  may  not  appear  where  expected. 
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The  -gamma  and  -render  options  are  supported  only  on  the  PaintJet  XL  printers. 
The  -slide  option  is  not  supported  for  LaserJet  printers. 

The  -split  option  is  not  supported  for  HP  printers. 

See  Also 

xwd,  xdpr,  xwud,  X 

Copyright 

Copyright  1988,  Massachusetts  Institute  of  Technology. 

Copyright  1986,  Marvin  Solomon  and  the  University  of  Wisconsin. 

Copyright  1988,  Hewlett-Packard  Company. 

See  X for  a full  statement  of  rights  and  permissions. 
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Bob  Scheifler,  MIT; 

Angela  Bock  and  E.  Mike  Durbin,  Rich  Inc.  (grayscale); 

Larry  Rupp,  Hewlett-Packard  (HP  printer  support). 


X Window  System  User’s  Guide 


457 


Reference  Pages 


xprop 


Display  Properties  for  X — 


Name 

xprop  - display  window  and  font  properties  for  X. 

Syntax 

xprop  [options] 

Description 

The  xprop  utility  is  for  displaying  window  and  font  properties  in  an  X server.  One  window  or 
font  is  selected  using  the  command  line  arguments  or  in  the  case  of  a window,  by  clicking  on 
the  desired  window.  A list  of  properties  is  then  given,  possibly  with  formatting  information. 

For  each  of  these  properties,  its  value  on  the  selected  window  or  font  is  printed  using  the  sup- 
plied formatting  information  if  any.  If  no  formatting  information  is  supplied,  internal  defaults 
are  used.  If  a property  is  not  defined  on  the  selected  window  or  font,  “not  defined”  is  printed  as 
the  value  for  that  property.  If  no  property  list  is  given,  all  the  properties  possessed  by  the 
selected  window  or  font  are  printed. 

A window  may  be  selected  in  one  of  four  ways.  First,  if  the  desired  window  is  the  root  window, 
the  -root  option  may  be  used.  If  the  desired  window  is  not  the  root  window,  it  may  be 
selected  in  two  ways  on  the  command  line,  either  by  id  number  such  as  might  be  obtained  from 
xwininfo , or  by  name  if  the  window  possesses  a name.  The  -id  option  selects  a window  by  id 
number  in  either  decimal  or  hex  (must  start  with  Ox)  while  the  -name  option  selects  a window 
by  name. 

The  last  way  to  select  a window  docs  not  involve  the  command  line  at  all.  If  none  of  -font, 
-id,  -name,  and  -root  are  specified,  a crosshair  cursor  is  displayed  and  the  user  allowed  to 
choose  any  visible  window  by  pressing  any  pointer  button  in  the  desired  window.  If  it  is 
desired  to  display  properties  of  a font  as  opposed  to  a window,  the  -font  option  must  be  used. 

Other  than  the  above  four  options,  the  -help  option  for  obtaining  help,  and  the  -grammar 
option  for  listing  the  full  grammar  for  the  command  line,  all  the  other  command  line  options  are 
used  in  specifing  both  the  format  of  the  properties  to  be  displayed  and  how  to  display  them. 
The  -len  n option  specifies  that  at  most  n bytes  of  any  given  property  will  be  read  and 
displayed.  This  is  useful,  for  example,  when  displaying  the  cut  buffer  on  the  root  window 
which  could  run  to  several  pages  if  displayed  in  full. 

Normally  each  property  name  is  displayed  by  printing  first  the  property  name,  then  its  type  (if  it 
has  one)  in  parentheses,  followed  by  its  value.  The  -notype  option  specifies  that  property 
types  should  not  be  displayed.  The  -f  s option  is  used  to  specify  a file  containing  a list  of  for- 
mats for  properties,  while  the  -f  option  is  used  to  specify  the  format  for  one  property. 

The  formatting  information  for  a property  actually  consists  of  two  parts,  a format  and  a 
d format.  The  format  specifies  the  actual  formatting  of  the  property  (i.e.,  is  it  made  up  of 
words,  bytes,  or  longs?,  etc.)  while  the  d format  specifies  how  the  property  should  be 
displayed. 

The  following  paragraphs  describe  how  to  construct  formats  and  d formats.  However,  for 
the  vast  majority  of  users  and  uses,  this  should  not  be  necessary  as  the  built  in  defaults  contain 
the  formats  and  d formats  necessary  to  display  all  the  standard  properties.  It  should  only  be 
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necessary  to  specify  formats  and  d formats  if  a new  property  is  being  dealt  with  or  the  user 
dislikes  the  standard  display  format.  New  users  especially  are  encouraged  to  skip  this  part. 

A format  consists  of  one  of  0,  8,  16,  or  32  followed  by  a sequence  of  one  or  more  format 
characters.  The  0,  8,  16,  or  32  specifies  how  many  bits  per  field  there  are  in  the  property.  Zero 
is  a special  case  meaning  use  the  field  size  information  associated  with  the  property  itself.  (This 
is  only  needed  for  special  cases  like  type  INTEGER  which  is  actually  three  different  types 
depending  on  the  size  of  the  fields  of  the  property.) 

A value  of  8 means  that  the  property  is  a sequence  of  bytes  while  a value  of  16  would  mean  that 
the  property  is  a sequence  of  words.  The  difference  between  these  two  lies  in  the  fact  that  the 
sequence  of  words  will  be  byte  swapped  while  the  sequence  of  bytes  will  not  be  when  read  by  a 
machine  of  the  opposite  byte  order  of  the  machine  that  orginally  wrote  the  property.  For  more 
information  on  how  properties  are  formatted  and  stored,  consult  Volume  One,  Xlib  Program- 
ming Manual. 


Once  the  size  of  the  fields  has  been  specified,  it  is  necessary  to  specify  the  type  of  each  field 
(i.e.,  is  it  an  integer,  a string,  an  atom,  or  what?).  This  is  done  using  one  format  character  per 
field.  If  there  are  more  fields  in  the  property  than  format  characters  supplied,  the  last  character 
will  be  repeated  as  many  times  as  necessary  for  the  extra  fields.  The  format  characters  and 
their  meaning  are  as  follows: 

a The  field  holds  an  atom  number.  A field  of  this  type  should  be  of  size  32. 

b The  field  is  an  boolean.  A 0 means  false  while  anything  else  means  true, 

c The  field  is  an  unsigned  number,  a cardinal, 
i The  field  is  a signed  integer. 

The  field  is  a set  of  bit  flags,  1 meaning  on. 

This  field  and  the  next  ones  until  either  a 0 or  the  end  of  the  property  represent  a 
sequence  of  bytes.  This  format  character  is  only  usable  with  a field  size  of  8 and  is 
most  often  used  to  represent  a string. 

The  field  is  a hex  number  (like  ’c’  but  displayed  in  hex  - most  useful  for  displaying 
window  ids  and  the  like). 


m 


An  example  format  is  32ica  which  is  the  format  for  a property  of  three  fields  of  32  bits  each, 
the  first  holding  a signed  integer,  the  second  an  unsigned  integer,  and  the  third  an  atom. 

The  format  of  a d format  (unlike  that  of  a format)  is  not  so  rigid.  The  only  limitations  on  a 
d format  is  that  it  may  not  start  with  a letter  or  a dash.  This  is  so  that  it  can  be  distingished 
from  a property  name  or  an  option.  A d format  is  a text  string  containing  special  characters 
instructing  that  various  fields  be  printed  at  various  points  in  a manner  similar  to  the  formatting 
string  used  by  print f.  For  example,  the  d format  “ is  ( $0,  $1  \)\n”  would  render  the  POINT  3, 
-4  which  has  a format  of  32ii  as  “ is  ( 3,  -4  )\n”. 

Any  character  other  than  a $,  ?,\,  or  a ( in  a d format  prints  as  itself.  To  print  out  one  of  $,  ?, 
\,  or  ( preceed  it  by  a \.  For  example,  to  print  out  a $,  use  NS.  Several  special  backslash 
sequences  are  provided  as  shortcuts.  \n  will  cause  a newline  to  be  displayed  while  \t  will  cause 
a tab  to  be  displayed.  \o  where  o is  an  octal  number  will  display  character  number  o. 
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A $ followed  by  a number  n causes  field  number  n to  be  displayed.  The  format  of  the 
displayed  field  depends  on  the  formatting  character  used  to  describe  it  in  the  corrsponding 
format.  For  example,  if  a cardinal  is  described  by  ’c’  it  will  print  in  decimal  while  if  it  is 
described  by  a V it  will  be  displayed  in  hex. 

If  the  field  is  not  present  in  the  property  (this  is  possible  with  some  properties),  <field  not  avail- 
able>  is  displayed  instead.  $n+  will  display  field  number  n then  a comma  then  field  number 
n+1  then  another  comma  then  . . . until  the  last  field  defined.  If  field  n is  not  defined,  nothing 
is  displayed.  This  is  useful  for  a property  that  is  a list  of  values. 

A ? is  used  to  start  a conditional  expression,  a kind  of  if-then  statement.  ?exp(text)  will  dis- 
play text  if  and  only  if  exp  evaluates  to  non-zero.  This  is  useful  for  two  things.  First,  it 
allows  fields  to  be  displayed  if  and  only  if  a flag  is  set.  And  second,  it  allows  a value  such  as  a 
state  number  to  be  displayed  as  a name  rather  than  just  as  a number.  The  syntax  of  exp  is  as 
follows: 

exp  ::=  term  I term=exp  \ \exp 
term ::=  n I $n  I mn 

The  ! operator  is  a logical  “not”,  changing  0 to  1 and  any  non-zero  value  to  0.  = is  an  equality 
operator.  Note  that  internally  all  expressions  are  evaluated  as  32  bit  numbers  so  -1  is  not  equal 
to  65535.  = returns  1 if  the  two  values  are  equal  and  0 if  not.  n represents  the  constant  value  n 
while  $n  represents  the  value  of  field  number  n.  ran  is  1 if  flag  number  n in  the  first  field  hav- 
ing format  character  ’m’  in  the  corrsponding  format  is  1, 0 otherwise. 

Examples:  ?m3(count:  $3Nn)  displays  field  3 with  a label  of  count  if  and  only  if  flag  number  3 
(count  starts  at  0!)  is  on.  ?$2=0(True)?!$2=0(False)  displays  the  inverted  value  of  field  2 as  a 
boolean. 

In  order  to  display  a property,  xprop  needs  both  a format  and  a d format.  Before  xprop  uses 
its  default  values  of  a format  of  32x  and  a d format  of  “ = { $0+  }\n”,  it  searches  several 
places  in  an  attempt  to  find  more  specific  formats.  First,  a search  is  made  using  the  name  of  the 
property.  If  this  fails,  a search  is  made  using  the  type  of  the  property.  This  allows  type  STRING 
to  be  defined  with  one  set  of  formats  while  allowing  property  WM_NAME  which  is  of  type 
STRING  to  be  defined  with  a different  format.  In  this  way,  the  display  formats  for  a given  type 
can  be  overridden  for  specific  properties. 

The  locations  searched  are  in  order:  the  format  if  any  specified  with  the  property  name  (as  in  8x 
WM_NAME),  the  formats  defined  by  -f  options  in  last  to  first  order,  the  contents  of  the  file 
specified  by  the  -f  s option  if  any,  the  contents  of  the  file  specified  by  the  environment  variable 
XPROPFORMATS  if  any,  and  finally  xprop' s built  in  file  of  formats. 

The  format  of  the  files  refered  to  by  the  -f  s option  and  the  XPROPFORMATS  variable  is  one  or 
more  lines  of  the  following  form: 

name  format  [ d format ] 

Where  name  is  either  the  name  of  a property  or  the  name  of  a type,  format  is  the  format  to 
be  used  with  name  and  dformat  is  the  dformat  to  be  used  with  name.  If  dformat  is  not 
present,  “ = $0+\n”  is  assumed. 
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Options 

-help 

Prints  out  a summary  of  command  line  options. 

-grammar 

-id  id 

Prints  out  a detailed  grammar  for  all  command  line  options. 

Allows  the  user  to  select  window  id  on  the  command  line  rather  than  using 
the  pointer  to  select  the  target  window.  This  is  very  useful  in  debugging  X 
applications  where  the  target  window  is  not  mapped  to  the  screen  or  where 
the  use  of  the  pointer  might  be  impossible  or  interfere  with  the  application. 

-name  name 

Allows  the  user  to  specify  that  the  window  named  name  is  the  target  window 
on  the  command  line  rather  than  using  the  pointer  to  select  the  target  window. 

-font  font 

Allows  the  user  to  specify  that  the  properties  of  font  font  should  be 
displayed. 

-root 

Specifies  that  X’s  root  window  is  the  target  window.  This  is  useful  in  situa- 

tions  where  the  root  window  is  completely  obscured, 
-display  [host] : server[ . screen] 


-len  n 

Allows  you  to  specify  the  server  to  connect  to.  For  example, 

xprop  -display  your  node: 0.1 

specifies  screen  1 on  server  0 on  the  machine  your  node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  any  case. 

Specifies  that  at  most  n bytes  of  any  property  should  be  read  or  displayed. 

-notype 

-f s file 

Specifies  that  the  type  of  each  property  should  not  be  displayed. 

Specifies  that  file  file  should  be  used  as  a source  of  more  formats  for  pro- 
perties. 

-remove  propname 

Specifies  the  name  of  a property  to  be  removed  from  the  indicated  window. 

-f  name  format  [ dformat ] 

Specifies  that  the  format  for  name  should  be  format  and  that  the  dformat 


-frame 

for  name  should  be  dformat.  If  dformat  is  missing,  “ = $0+\n”  is 
assumed. 

Specifies  that  when  selecting  a window  by  hand  (i.e.,  if  none  of  -name, 
-root,  or  -id  are  given),  xprop  should  look  at  the  window  manager  frame 
(if  any)  instead  of  looking  for  the  client  window.  (Available  as  of  Release  4.) 

-spy 

Indicates  that  xprop  should  examine  window  properties  forever,  looking  for 
property  change  events.  (Available  as  of  Release  4.) 

X Window  System  User’s  Guide 


461 


Reference  Pages 


xprop 


(continued) 


Display  Properties  for  X 


Examples 

To  display  the  name  of  the  root  window:  prop  -root  wm_name 
To  display  the  window  manager  hints  for  the  clock:  xprop  -name  xclock  WM_HINTS 
To  display  the  start  of  the  cut  buffer:  xprop  -root  -len  100  CUT_BUFFER0 
To  display  the  point  size  of  the  fixed  font:  xprop  -font  fixed  P0INT_SIZE 
To  display  all  the  properties  of  window  # 0x200007:  xprop  -id  0x200007 

Environment  Variables 

XPROPFORMATS  Specifies  the  name  of  a file  from  which  additional  formats  are  to  be 

obtained. 

See  Also 

X,  xwininfo 

Author 

Mark  Lillibridge,  MIT  Project  Athena. 
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Name 

xpseudoroot  - create  a pseudo  root  window. 

Syntax 

xpseudoroot  [options] 

Description 

This  client  is  available  in  Release  3 only.  It  is  experimental  and  should  be  used  with  cau- 
tion. (Please  see  Warning  below.)  xpseudoroot  has  been  removed  from  the  X distribution  as 
of  Release  4. 

The  xpseudoroot  program  allows  you  to  create  pseudo  root  windows  as  outlined  in  the  Inter- 
Client  Communications  Conventions  Manual.  By  default  it  just  makes  a copy  of  the  normal 
root  window,  but  command  line  options  may  be  used  to  alter  much  of  the  screen-related  infor- 
mation. 

The  command  line  argument  property_name  specifies  the  name  of  a property  on  the 
screen’s  real  root  window  in  which  to  store  the  pseudo  root  information.  Applications  can  be 
run  within  the  pseudo  root  window  by  appending  .property_name  to  the 
server,  screen  part  of  the  display  name;  for  example:  expo : 0 . 0 .property_name. 

Warning 

This  is  experimental  code  for  implementing  pseudo  root  windows  as  specified  by  the  Inter-Cli- 
ent Communications  Conventions  Manual.  The  interfaces  that  it  provides  should  be  considered 
private  to  the  MIT  implementation  of  Xlib  and  will  change  in  the  next  release.  The  interfaces 
that  it  provides  should  not  be  incorporated  into  any  toolkits  or  applications.  No  effort  will  be 
made  to  provide  backward  compatibility. 

Options 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xpsaudoroot  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-geometry  geometry 

The  xpseudoroot  window  is  created  with  the  specified  size  and  location  deter- 
mined by  the  supplied  geometry  specification.  The  -geometry  option  can 
be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that 
begins  with  “g.”  The  argument  to  the  geometry  option  (geometry)  is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff. 
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-visuals  visualid 

Specifies  a list  of  visuals  to  support  on  the  pseudo  root  window.  Any  number 
of  numeric  visual  identifiers  (in  hex,  octal,  or  decimal)  may  be  supplied  using 
the  -visuals  option. 

-colormap  colormapid 

Specifies  the  numeric  colormap  identifier  to  be  associated  with  the  pseudo 
root  window. 

-Colormap  visualid 

Specifies  a numeric  visual  identifier  to  be  used  in  creating  a new  colormap  for 
the  pseudo  root  window.  If  this  option  is  given,  xpseudoroot  will  create  a 
new  colormap  from  the  given  visual  and  set  the  black  and  white  pixel  fields 
to  the  desired  colors. 

-white  pixel 

Specifies  the  numeric  pixel  value  to  use  for  WhitePixel  when  creating  a 
new  colormap  with  -Colormap.  The  default  is  to  copy  the  real  screen’s 
WhitePixel. 

-White  colorname 

Specifies  the  color  to  use  when  setting  WhitePixel  in  newly  created  color- 
maps.  It  may  be  used  with  -white  to  create  arbitrary  WhitePixels. 

-black  pixel 

Specifies  the  numeric  pixel  value  to  use  for  BlackPixel  when  creating  a 
new  colormap  with  -Colormap.  The  default  is  to  copy  the  real  screen’s 
BlackPixel. 

-Black  colorname 

Specifies  the  color  to  use  when  setting  BlackPixel  in  newly  created  color- 
maps.  It  may  be  used  with  -black  to  create  arbitrary  BlackPixels. 

-empty  Indicates  that  any  colormaps  created  with  -Colormap  should  not  have 

BlackPixel  and  WhitePixel  preallocated  (although  the  values  may  still 
be  set  with  -black  and  -white).  This  leaves  as  much  room  as  possible  for 
running  applications  that  would  otherwise  not  find  enough  colors.  This  is  not 
for  general  use  as  it  guarantees  that  an  application  will  be  displayed  in  incor- 
rect colors. 

-max  number  Specifies  the  maximum  number  of  installed  colormaps  that  will  be  allowed  on 
this  screen.  The  default  is  to  use  the  real  screen’s  value. 

-min  number  Specifies  the  minimum  number  of  installed  colormaps  that  will  be  allowed  on 
this  screen.  The  default  is  to  use  the  real  screen’s  value. 

-backingstore  when 

Specifies  when  backing  store  window  attributes  will  be  honored  and  takes 
one  of  the  following  arguments:  NotUseful,  WhenMapped,  or  Always. 
The  default  is  to  use  the  real  screen’s  value. 
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-saveunders  boolean 

Specifies  whether  or  not  this  screen  supports  save-unders  and  takes  one  of  the 
following  arguments:  yes  or  no. 

-name  string 

Specifies  the  name  to  be  used  for  the  pseudo  root  window. 


See  Also 

X,  xdpyinfo,  xwininfo,  xprop;  Volume  One,  Xlib  Programming  Manual 

Bugs 

This  is  a sample  program  that  is  primarily  intended  as  a testbed  for  ICCCM  pseudo  roots.  It 
should  not  be  incorporated  into  any  toolkit  or  application. 


Author 

Jim  Fulton,  MIT  X Consortium. 
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Name 

xrdb  - X server  resource  database  utility. 

Syntax 

xrdb  [options]  [ filename ] 

Description 

xrdb  is  used  to  get  or  set  the  contents  of  the  RESOURCE_MANAGER  property  on  the  root  win- 
dow of  screen  0.  You  would  normally  run  this  program  from  your  X startup  file. 

The  resource  manager  (used  by  the  Xlib  routine  XGetDefault( 3X)  and  the  X Toolkit)  uses  the 
RESOURCE_MANAGER  property  to  get  user  preferences  about  color,  fonts,  and  so  on  for  appli- 
cations. Having  this  information  in  the  server  (where  it  is  available  to  all  clients)  instead  of  on 
disk,  solves  the  problem  in  previous  versions  of  X that  required  you  to  maintain  defaults  files 
on  every  machine  that  you  might  use.  It  also  allows  for  dynamic  changing  of  defaults  without 
editing  files. 

For  compatibility,  if  there  is  no  RESOURCE_MANAGER  property  defined  (either  because  xrdb 
was  not  run  or  the  property  was  removed),  the  resource  manager  will  look  for  a file  called  Xde- 
faults  in  your  home  directory. 

The  filename  (or  the  standard  input  if  - or  no  input  file  is  given)  is  optionally  passed  through 
the  C preprocessor  with  the  following  symbols  defined,  based  on  the  capabilities  of  the  server 
being  used: 

SERVERHOST =hostname 
HOST -hostname 

The  hostname  portion  of  the  display  to  which  you  are  connected. 

WIDTH=n umber 

The  width  of  the  default  screen  in  pixels. 

H E I G H T = n u mb  e r 

The  height  of  the  default  screen  in  pixels. 

X_RESOLUTION=/J  umber 

The  x resolution  of  the  default  screen  in  pixels  per  meter. 

Y_RE  SOLUTIONS  umber 

The  y resolution  of  the  default  screen  in  pixels  per  meter. 

P LANE S =n umber 

The  number  of  bit  planes  (the  depth)  of  the  root  window  of  the  default  screen. 
CLASS =visualclass 

One  of  StaticGray,  Grayscale,  StaticColor,  PsuedoColor, 
TrueColor,  DirectColor.  This  is  the  visual  class  of  the  root  window 
of  the  default  screen. 

COLOR  Defined  only  if  CLASS  is  one  of  StaticColor,  PsuedoColor,  True- 

Color,  or  DirectColor. 
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BIT  S_PER_RBG=/3  umber 

The  number  of  significant  bits  in  an  RGB  color  specification.  This  is  the  log 
base  2 of  the  number  of  distinct  shades  of  each  primary  that  the  hardware  can 
generate.  Note  that  it  is  usually  not  related  to  the  number  of  PLANES. 

CLIENTHOST=host/iame 

The  name  of  the  host  on  which  xrdb  is  running.  (Available  as  of  Release  4.) 
RELEASE =number 

The  vendor  release  number  for  the  server.  The  interpretation  of  this  number 
will  vary  depending  on  VENDOR.  (Available  as  of  Release  4.) 

REVISION =number 

The  X protocol  minor  version  supported  by  this  server  (currently  0). 
VERSION=number 

The  X protocol  major  version  supported  by  this  server  (should  always  be  1 1). 
VENDOR =number 

A string  specifying  the  vendor  of  the  server.  (Available  as  of  Release  4.) 
Lines  that  begin  with  an  exclamation  mark  (!)  are  ignored  and  may  be  used  as  comments. 

Options 

xrdb  accepts  the  following  options: 

-help  This  option  (or  any  unsupported  option)  will  cause  a brief  description  of  the 

allowable  options  and  parameters  to  be  printed. 

-display  [host] : server! . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example: 

xrdb  -display  your_node: 0.0 

specifies  screen  0 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 

-cpp  filename 

Specifies  the  pathname  of  the  C preprocessor  program  to  be  used.  Although 
xrdb  was  designed  to  use  CPP,  any  program  that  acts  as  a filter  and  accepts 
the  -D,  - I,  and  -u  options  may  be  used. 

-nocpp  Indicates  that  xrdb  should  not  run  the  input  file  through  a preprocessor  before 

loading  it  into  the  RESOURCE_MANAGER  property. 

-symbols  Indicates  that  the  symbols  that  are  defined  for  the  preprocessor  should  be 
printed  onto  the  standard  output.  This  option  can  be  used  in  conjunction  with 
-query,  but  not  with  the  options  that  change  the  RESOURCE_MANAGER 
property. 
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-query 


-load 


-merge 


-quiet 


-remove 


-retain 


Indicates  that  the  current  contents  of  the  RESOURCE_MANAGER  property 
should  be  printed  onto  the  standard  output.  Note  that  since  preprocessor 
commands  in  the  input  resource  file  are  part  of  the  input  file,  not  part  of  the 
property,  they  won’t  appear  in  the  output  from  this  option.  The  -edit 
option  can  be  used  to  merge  the  contents  of  the  property  back  into  the  input 
resource  file  without  damaging  preprocessor  commands. 

Indicates  that  the  input  should  be  loaded  as  the  new  value  of  the 
RESOURCE_MANAGER  property,  replacing  whatever  was  there  (i.e.,  the  old 
contents  are  removed).  This  is  the  default  action. 

Indicates  that  the  input  should  be  merged  with,  instead  of  replacing,  the  cur- 
rent contents  of  the  RESOURCE_MANAGER  property.  Since  xrdb  can  read 
the  standard  input,  this  option  can  be  used  to  the  change  the  contents  of  the 
RESOURCE_MANAGER  property  directly  from  a terminal  or  from  a shell 
script.  Note  that  this  option  does  a lexicographic  sorted  merge  of  the  two 
inputs,  which  is  almost  certainly  not  what  you  want,  but  remains  for  back- 
ward compatibility. 

Indicates  that  changes  to  the  property  (when  used  with  -load)  or  to  the 
resource  file  (when  used  with  -edit)  should  be  shown  on  the  standard 
output,  but  should  not  be  performed.  (Available  as  of  Release  4.) 

Indicates  that  warning  about  duplicate  entries  should  not  be  displayed. 
(Available  as  of  Release  4.) 

Indicates  that  the  RESOURCE_MANAGER  property  should  be  removed  from 
its  window. 

Indicates  that  the  server  should  be  instructed  not  to  reset  if  xrdb  is  the  first 
client.  (Available  as  of  Release  4.) 


-edit  filename 

Indicates  that  the  contents  of  the  RESOURCE_MANAGER  property  should  be 
edited  into  the  given  file,  replacing  any  values  already  listed  there.  This 
allows  you  to  put  changes  that  you  have  made  to  your  defaults  back  into  your 
resource  file,  preserving  any  comments  or  preprocessor  lines. 

-backup  string 

Specifies  a suffix  to  be  appended  to  the  filename  used  with  -edit  to  gener- 
ate a backup  file. 


-Dname [=vaiue] 

Is  passed  through  to  the  preprocessor  and  is  used  to  define  symbols  for  use 
with  conditionals  such  as  ttifdef. 

-U name  Is  passed  through  to  the  preprocessor  and  is  used  to  remove  any  definitions  of 

this  symbol. 

-Idirectory  Is  passed  through  to  the  preprocessor  and  is  used  to  specify  a directory  to 
search  for  files  that  are  referenced  with  #include. 


468 


X Window  System  User's  Guide 


X Server  Resource  Database  Utility 


(continued) 


xrdb 


Files 

Generalizes  " I.Xdefaults  files. 

See  Also 

X,  XGetDefault(3X),  Xlib  Resource  Manager 

Bugs 

The  default  for  no  arguments  should  be  to  query,  not  to  overwrite,  so  that  it  is  consistent  with 
other  programs. 

Authors 

Phil  Karlton,  rewritten  from  the  original  by  Jim  Gettys.  Copyright  1988,  Digital  Equipment 
Corporation. 
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Name 

xrefresh  - refresh  all  or  pari  of  an  X screen. 

Syntax 

xrefresh [options] 

Description 

xrefresh  is  a simple  X program  that  causes  all  or  part  of  your  screen  to  be  repainted.  This  is 
useful  when  system  messages  have  displayed  on  your  screen,  xrefresh  maps  a window  on  top 
of  the  desired  area  of  the  screen  and  then  immediately  unmaps  it,  causing  refresh  events  to  be 
sent  to  all  applications.  By  default,  a window  with  no  background  is  used,  causing  all  applica- 
tions to  repaint  “smoothly.”  However,  the  various  options  can  be  used  to  indicate  that  a solid 
background  (of  any  color)  or  the  root  window  background  should  be  used  instead. 

Options 

-white  Use  a white  background.  The  screen  just  appears  to  flash  quickly,  and  then 

repaints. 

-black  Use  a black  background  (in  effect,  turning  off  all  of  the  electron  guns  to  the 

tube).  This  can  be  somewhat  disorienting  as  everything  goes  black  for  a 
moment. 

-solid  color 

Use  a solid  background  of  the  specified  color.  Try  green. 

-root  Use  the  root  window  background. 

-none  This  is  the  default.  All  of  the  windows  simply  repaint. 

-geometry  geometry 

Specifies  the  portion  of  the  screen  to  be  repainted.  The  -geometry  option 
can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option 
that  begins  with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is 
referred  to  as  a “standard  geometry  string,”  and  has  the  form  widthx.- 
height±xoff±yoff. 

-display  [ host] : server[ . screen] 

Allows  you  to  specify  the  server  and  screen  to  refresh.  For  example,  host 
specifies  the  machine,  server  specifies  the  server  number,  and  screen 
specifies  the  screen  number.  For  example, 

xrefresh  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 
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Resources 

The  xrefresh  program  uses  the  routine  XGetDefault(3X)  to  read  defaults,  so  its  resource  names 
are  all  capitalized. 

Black, White, Solid, None,  Root 

Determines  what  sort  of  window  background  to  use. 

Geometry  Determines  the  area  to  refresh.  Not  very  useful. 

See  Also 

X 

Bugs 

It  should  have  just  one  default  type  for  the  background. 

Author 

Jim  Gettys,  Digital  Equipment  Corp.,  MIT  Project  Athena. 
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Name 

xset  - user  preference  utility  for  X. 

Syntax 

xset  [options] 

Description 

xset  is  used  to  set  various  user  preference  options  of  the  display  and  keyboard. 

Options 

Note  that  not  all  X implementations  are  guaranteed  to  honor  all  of  these  options. 

-display  [ host] : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  for  which  to  set  prefer- 
ences. host  specifies  the  machine,  server  specifies  the  server  number,  and 
screen  specifies  the  screen  number.  For  example, 

-display  your_node: 0 . 1 & 

specifies  screen  1 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  server  and  colon  (;)  are  necessary  in  all  cases. 

b Controls  bell  volume,  pitch,  and  duration.  The  b option  accepts  up  to  three 

numerical  parameters  ( volume , pitch,  and  duration),  a preceding  dash 
(-),  or  an  on/ of  f flag.  If  no  parameters  are  given,  or  the  on  flag  is  used,  the 
system  defaults  will  be  used.  If  the  dash  or  off  are  given,  the  bell  will  be 
turned  off.  If  only  one  numerical  parameter  is  given,  the  bell  volume  will 
be  set  to  that  value,  as  a percentage  of  its  maximum.  Likewise,  the  second 
numerical  parameter  specifies  the  bell  pitch,  in  hertz,  and  the  third  numeri- 
cal parameter  specifies  the  duration  in  milliseconds.  Note  that  not  all 
hardware  can  vary  the  bell  characteristics.  The  X server  will  set  the  charac- 
teristics of  the  bell  as  closely  as  it  can  to  the  user’s  specifications. 

-be  Controls  bug  compatibility  mode  in  the  server,  if  possible.  The  option  with  a 

bc  preceding  dash  (-)  disables  the  mode;  the  option  alone  enables  the  mode. 

The  need  for  this  option  is  determined  by  the  following  circumstances.  Vari- 
ous pre-R4  clients  pass  illegal  values  in  some  protocol  requests,  and  pre-R4 
servers  did  not  correctly  generate  errors  in  these  cases.  Such  clients,  when 
run  with  an  R4  server,  will  terminate  abnormally  or  otherwise  fail  to  operate 
correctly.  Bug  compatibility  mode  explicitly  reintroduces  certain  bugs  into 
the  X server,  so  that  many  such  clients  can  still  be  run. 

This  mode  should  be  used  with  care;  new  application  development  should  be 
done  with  this  mode  disabled.  Be  aware  that  the  server  must  support  the  MIT- 
SUNDRY-NONSTANDARD  protocol  extension  in  order  for  this  option  to  work. 
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c Controls  key  click.  The  c option  can  take  an  optional  value,  a preceding  dash 

(-),  or  an  on/off  flag.  If  no  parameter  or  the  on  flag  is  given,  the  system 
defaults  will  be  used.  If  the  dash  or  off  flag  is  used,  the  keyclick  will  be  dis- 
abled. If  a value  from  0 to  100  is  given,  it  is  used  to  indicate  volume,  as  a 
percentage  of  the  maximum.  The  X server  will  set  the  volume  to  the  nearest 
value  that  the  hardware  can  support. 

fp=  path  Sets  the  font  path  used  by  the  server,  path  must  be  a directory  or  a comma- 
separated  list  of  directories.  The  directories  are  interpreted  by  the  server,  not 
the  client,  and  are  server-dependent.  (Directories  that  do  not  contain  font 
databases  created  by  mkfontdir  will  be  ignored  by  the  server.) 

fp  default  Restores  the  default  font  path. 

f p rehash  Causes  the  server  to  reread  the  font  databases  in  the  current  font  path.  This  is 
generally  only  used  when  adding  new  fonts  to  a font  directory  (after  running 
mkfontdir  to  recreate  the  font  database). 


-fp  path  or  fp-  path 

The  -fp  and  fp-  options  remove  elements  from  the  current  font  path,  path 
must  be  a director)'  or  comma- separated  list  of  directories. 

+fp  path  or  f p+  path 

The  +fp  and  fp+  options  prepend  and  append  elements  to  the  current  font 
path,  respectively,  path  must  be  a director)'  or  comma- separated  list  of 
directories. 

led  Controls  the  turning  on  or  off  of  one  or  all  of  the  LEDs.  The  led  option 

accepts  an  optional  integer,  a preceding  dash  (-)  or  an  on/ off  flag.  If  no 
parameter  or  the  on  flag  is  given,  all  LEDs  are  turned  on.  If  a preceding  dash 
or  the  flag  of  f is  given,  all  LEDs  are  turned  off.  If  a value  between  1 and  32 
is  given,  that  LED  will  be  turned  on  or  off  depending  on  the  existence  of  a 
preceding  dash.  A common  LED  which  can  be  controlled  is  the  Caps  Lock 
LED.  xset  led  3 would  turn  led  #3  on.  xset  -led  3 would  turn  it 
off.  The  particular  LED  values  may  refer  to  different  LEDs  on  different  hard- 
ware. 

m Controls  the  mouse  parameters.  The  parameters  for  the  mouse  are  accel- 

eration and  threshold.  The  mouse,  or  whatever  pointer  the  machine  is 
connected  to,  will  go  acceleration  times  as  fast  when  it  travels  more 
than  threshold  pixels  in  a short  time.  This  way,  the  mouse  can  be  used  for 
precise  alignment  when  it  is  moved  slowly,  yet  it  can  be  set  to  travel  across 
the  screen  in  a flick  of  the  wrist  when  desired.  One  or  both  parameters  for  the 
m option  can  be  omitted,  but  if  only  one  is  given,  it  will  be  interpreted  as  the 
acceleration.  If  no  parameters  or  the  flag  default  is  used,  the  system 
defaults  will  be  seL 

p Controls  pixel  color  values.  The  parameters  are  the  color  map  entry  number 

in  decimal,  and  a color  specification.  The  root  background  colors  may  be 
changed  on  some  servers  by  altering  the  entries  for  BlackPixel  and 
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WhitePixel.  Although  these  are  often  0 and  1,  they  need  not  be.  Also,  a 
server  may  choose  to  allocate  those  colors  privately,  in  which  case  an  error 
will  be  generated.  The  map  entry  must  not  be  a read-only  color,  or  an  error 
will  result. 

r Controls  the  autorepeat.  If  a preceding  dash  or  the  off  flag  is  used, 

autorepeat  will  be  disabled.  If  no  parameters  or  the  on  flag  is  used, 
autorepeat  will  be  enabled. 

s Controls  the  screen  saver  parameters.  The  s option  accepts  up  to  two  numer- 

ical parameters  (time  and  cycle),  a blank/noblank  flag,  an 
expose/noexpose  flag,  an  on/off  flag,  or  the  default  flag.  If  no 
parameters  or  the  default  flag  is  used,  the  system  will  be  set  to  its  default 
screen  saver  characteristics.  The  on/off  flags  simply  turn  the  screen  saver 
functions  on  or  off.  The  blank  flag  sets  the  preference  to  blank  the  video  (if 
the  hardware  can  do  so)  rather  than  display  a background  pattern,  while 
noblank  sets  the  preference  to  display  a pattern  rather  than  blank  the  video. 
The  expose  flag  sets  the  preference  to  allow  window  exposures  (the  server 
can  freely  discard  window  contents),  while  noexpose  sets  the  preference  to 
disable  screen  saver  unless  the  server  can  regenerate  the  screens  without 
causing  exposure  events.  The  time  and  cycle  parameters  for  the  screen 
saver  function  determine  how  long  the  server  must  be  inactive  for  screen  sav- 
ing to  activate,  and  the  period  to  change  the  background  pattern  to  avoid  bum 
in,  respectively.  The  arguments  are  specified  in  seconds.  If  only  one  numeri- 
cal parameter  is  given,  it  will  be  used  for  the  time. 

q Gives  you  information  on  the  current  settings.  (In  Release  3,  the  query 

option  can  also  be  used.) 

These  settings  will  be  reset  to  default  values  when  you  log  out. 

See  Also 

X,  Xserver,  xmodmap,  xrdb,  xsetroot 

Authors 

Bob  Scheifler,  MIT  Laboratory  for  Computer  Science; 

David  Krikorian,  MIT  Project  Athena  (Xll  version). 
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Name 

xsetroot  - root  window  parameter  setting  utility. 

Syntax 

xsetroot [options] 

Description 

xsetroot  allows  you  to  tailor  the  appearance  of  the  root  (background)  window  on  a display.  You 
can  experiment  with  xsetroot  until  you  find  a look  that  you  like,  then  put  the  xsetroot  command 
that  produces  it  into  your  X startup  file.  If  you  do  not  specify  any  options  or  you  specify  -def , 
the  window  is  reset  to  its  defaults.  The  -def  option  can  be  specified  along  with  other  options 
and  only  the  non-specified  characteristics  will  be  reset  to  the  default  state. 

Options 

xsetroot  accepts  the  following  options. 

Only  one  of  the  background  color/tile  changing  options  (-solid,  -gray,  -grey,  -bitmap, 
or  -mod)  may  be  specified  at  a time,  color  can  be  specified  as  a color  name  or  an  RGB 
value. 

-help  Displays  a brief  description  of  the  allowable  options. 

-def  Resets  unspecified  attributes  to  the  default  values;  the  background  to  the  gray 

mesh  background  and  the  pointer  to  the  hollow  X pointer.  If  you  specify  def 
and  other  options,  only  the  non-specified  options  are  reset  to  their  defaults. 

-cursor  cursor  file  mask  file 

Specifies  the  cursor  shape  to  use  as  the  root  window  pointer.  The  cursor- 
file  and  maskfile  are  bitmaps  made  with  the  bitmap  client.  Refer  to 
Chapter  6,  Graphics  Utilities , for  more  information  on  creating  bitmaps.  The 
mask  file  may  need  to  be  all  black  until  you  are  accustomed  to  the  way  masks 
work.  The  default  root  window  pointer  is  an  X cursor. 

-cursor_name  standard_cursor_name 

Changes  the  root  window  cursor  to  one  of  the  standard  cursors  from  the  cur- 
sor font.  See  Appendix  D for  a list  and  pictures  of  the  Standard  Cursors.  To 
specify  a cursor  name  as  an  argument  to  a command  line  option,  the  XC_  pre- 
fix must  be  stripped  from  the  name.  (This  option  is  available  as  of  Release  4.) 

-bitmap  filename 

Uses  the  bitmap  specified  in  the  file  to  set  the  window  pattern.  The  entire 
background  is  made  up  of  repeated  tiles  of  the  bitmap.  You  can  make  your 
own  bitmap  files  using  the  bitmap  client  or  you  can  use  those  available  with 
X,  in  the  directory  lusrlinclude/X  1 1 /bitmaps . The  default  is  gray  mesh. 

-mod  x y Makes  a plaid-like  grid  pattern  on  your  screen,  x and  y are  integers  ranging 
from  1 to  16.  Zero  and  negative  numbers  are  taken  as  1. 
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-gray  or -grey 

Creates  a grey  background. 

Sets  the  foreground  color  of  the  root  window.  Foreground  and  background 
colors  are  meaningful  only  in  combination  with  -cursor,  -bitmap,  or 
-mod.  The  default  is  black. 

Sets  the  background  color  of  the  root  window.  Foreground  and  background 
colors  are  meaningful  only  in  combination  with  -cursor,  -bitmap,  or 
-mod.  The  default  is  white. 

Reverses  the  foreground  color  and  the  background  color  when  used  with 
another  option  such  as  -mod.  -rv  without  another  specified  option  returns 
the  root  (background)  window  to  the  default  state. 

-solid  color 

Sets  the  root  window  color.  The  default  is  gray  mesh. 

-name  string 

Sets  the  name  of  the  background  window  to  string.  There  is  no  default 
value.  Usually,  a name  is  assigned  to  a window  so  that  the  window  manager 
can  use  a text  representation  when  the  window  is  converted  to  an  icon.  This 
option  also  allows  a client  to  refer  to  the  root  window  by  name. 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server,  and  screen  of  the  root  window,  host 
specifies  the  machine,  server  specifies  the  server  number,  and  screen 
specifies  the  screen  number.  For  example, 

% xsetroot  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 


-fg  color 


-bg  color 


-rv 


See  Also 

X,  xset,  xrdb 

Author 

Mark  Lillibridge,  MIT  Project  Athena. 
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Name 

xstdcmap  - X standard  colormap  utility. 

Syntax 

xstdcmap  [options] 


— Define  Standard  Colormaps- 


f 


Description 

Available  as  of  Release  4,  the  xstdcmap  utility  can  be  used  to  selectively  define  standard  color- 
map  properties.  It  is  intended  to  be  run  from  a user’s  X startup  script  to  create  standard  color- 
map  definitions  in  order  to  facilitate  sharing  of  scarce  colormap  resources  among  clients. 
Where  at  all  possible,  colormaps  are  created  with  read-only  allocations. 


Options 

The  following  options  may  be  used  with  xstdcmap : 

-display  host  [:  server]  [.  screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xstdcmap  -display  your_node: 0.1 

specifies  screen  1 of  server  0 on  the  machine  your_node.  Either  or  both  the 
host  and  screen  elements  to  the  display  specification  can  be  omitted.  If 
host  is  omitted,  the  local  machine  is  assumed.  If  screen  is  omitted,  screen 
0 is  assumed  (and  the  period  is  unnecessary).  The  colon  and  server  are 
necessary  in  all  cases. 

-all  Specifies  that  all  six  standard  colormap  properties  should  be  defined  on  each 

screen  of  the  display.  Not  all  screens  will  support  visuals  under  which  all  six 

standard  colormap  properties  are  meaningful,  xstdcmap  will  determine  the 
best  allocations  and  visuals  for  the  colormap  properties  of  a screen.  Any  pre- 
viously existing  standard  colormap  properties  will  be  replaced. 

-best  Specifies  that  the  RGB_BEST_MAP  should  be  defined. 

-blue  Specifies  that  the  RGB_BLUE_MAP  should  be  defined. 

-default  Specifies  that  the  RGB_DEFAULT_MAP  should  be  defined. 


-delete  map  Specifies  that  a standard  colormap  property  should  be  removed,  map  may  be 
one  of:  default,  best,  red,  green,  blue,  or  gray. 

-gray  Specifies  that  the  RGB_GRAY_MAP  should  be  defined. 

-green  Specifies  that  the  RGB_GREEN_MAP  should  be  defined. 

-help  Specifies  that  a brief  description  of  the  command  line  arguments  should  be 

printed  on  the  standard  error.  This  will  be  done  whenever  an  unhandled  argu- 
ment is  given  to  xstdcmap. 
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-red  Specifies  that  the  RGB_RED_MAP  should  be  defined. 

-verbose  Specifies  that  xstdcmap  should  print  logging  information  as  it  parses  its  input 
and  defines  the  standard  colormap  properties. 


See  Also 

x 


Author 

Donna  Converse,  MIT  X Consortium. 
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Name 

xterm  - window  terminal  emulator. 

Syntax 

xterm  [options] 

Description 

The  xterm  program  is  a terminal  emulator  for  the  X Window  System.  It  provides  DEC  VT102 
and  Tektronix  4014  compatible  terminals  for  programs  that  can’t  use  the  window  system 
directly.  If  the  underlying  operating  system  supports  terminal  resizing  capabilities  (for 
example,  the  SIGWINCH  signal  in  systems  derived  from  BSD  4.3),  xterm  will  use  the  facilities  to 
notify  programs  running  in  the  window  whenever  it  is  resized. 

The  VT102  and  Tektronix  4014  terminals  each  have  their  own  window  so  that  you  can  edit  text 
in  one  and  look  at  graphics  in  the  other  at  the  same  time.  To  maintain  the  correct  aspect  ratio 
(height/width),  Tektronix  graphics  will  be  restricted  to  the  largest  box  with  a 4014’s  aspect 
ratio  that  will  fit  in  the  window.  This  box  is  located  in  the  upper  left  area  of  the  window. 

Although  both  windows  can  be  displayed  at  the  same  time,  one  of  them  is  considered  the  active 
window  for  receiving  keyboard  input  and  terminal  output.  This  is  the  window  that  contains  the 
text  cursor  and  whose  border  highlights  whenever  the  pointer  is  in  either  window.  The  active 
window  can  be  chosen  through  escape  sequences,  the  VT  Options  menu  in  the  VT102  window, 
and  the  Tek  Options  menu  in  the  4014  window. 

The  Release  4 version  of  xterm  provides  four  menus  that  allow  you  to  manipulate  the  VT102 
and  Tektronix  windows:  Main  Options,  VT  Options,  Tek  Options,  and  VT  Fonts.  The  first  three 
menus  are  available  (with  slight  variations)  in  Release  3,  but  have  the  names  xterm.  Modes,  and 
Tektronix.  The  VT  Fonts  menu  is  available  as  of  Release  4. 

Options 

xterm  accepts  all  of  the  standard  X Toolkit  command  line  options  along  with  the  additional 
options  described  below.  Note  that  if  the  option  begins  with  a + instead  of  a -,  the  option  is 
restored  to  its  default  value.  (Specifying  the  default  with  +option  can  be  useful  for  overrid- 
ing the  opposite  value  in  an  Xresources  file  or  other  prior  resource  specification.) 

-help  Causes  xterm  to  print  out  a verbose  message  describing  its  options. 

-132  Causes  the  VT102  DECCOLM  escape  sequence,  which  switches  between  80 

and  132  column  mode,  to  be  recognized,  enabling  the  xterm  window  to  resize 
properly.  By  default,  the  DECCOLM  escape  sequence  is  ignored.  (See 
Appendix  C for  more  information  on  xterm  escape  sequences.) 

(This  option  can  be  turned  on  and  off  from  the  xterm  VT  Options  menu, 
described  below.) 

-ah/+ah  -ah  specifies  that  xterm  should  always  highlight  the  text  cursor  and  window 

borders.  By  default,  xterm  will  display  a hollow  text  cursor  whenever  the 
focus  is  lost  or  the  pointer  leaves  the  window.  +ah  sets  the  default. 
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-b  innerborder 

Specifies  the  width  of  the  inner  border  (the  distance  between  the  outer  edge 
of  the  characters  and  the  window  border)  in  pixels.  The  default  is  two  pixels. 

-C  Specifies  that  the  xterm  window  should  receive  console  output.  This  is  not 

supported  on  all  systems. 

-cc  characterclassrange : vaiue[, . . . ] 

Sets  classes  indicated  by  the  given  ranges  for  use  in  selecting  by  words.  See 
“Specifying  Character  Classes”  below. 

-cn/+cn  -cn  indicates  that  newlines  should  not  be  cut  in  line  mode  selections. 

+cn  indicates  that  newlines  should  be  cut  in  line  mode  selections,  (-cn  and 
+cn  are  available  as  of  Release  4.) 

-cr  color  Specifies  the  color  to  use  for  the  text  cursor.  The  default  is  to  use  the  same 
foreground  color  that  is  used  for  text 

-cu/+cu  -cu  enables  the  curses  fix.  Several  programs  that  use  the  curses( 3x)  cursor 

motion  package  have  some  difficulties  with  VT  102-compatible  terminals. 
The  bug  occurs  when  you  run  the  more  program  on  a file  containing  a line 
that  is  exactly  the  width  of  the  window  and  which  is  followed  by  a line  begin- 
ning with  a tab.  The  leading  tabs  are  not  displayed.  This  option  causes  the 
tabs  to  be  displayed  correctly. 

+cu  indicates  that  xterm  should  not  work  around  this  curses  bug. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

-e  command  [ arguments ] 

Specifies  the  command  (and  its  arguments)  to  be  run  in  the  xterm  window.  It 
also  sets  the  window  title  and  icon  name  to  be  the  name  of  the  program  being 
executed  if  neither  -T  or  -n  are  given  on  the  command  line.  The  -e  option, 
command  and  the  arguments  must  appear  last  on  the  xterm  command  line,  for 
example,  xterm  -rv  -e  more  bigf  ile  &. 

-fb  font  Uses  the  specified  font  as  the  bold  font.  This  font  must  be  the  same  height 
and  width  as  the  normal  font.  If  only  one  of  the  normal  or  bold  fonts  is  speci- 
fied, it  is  used  as  the  normal  font  and  the  bold  font  is  produced  by  overstrik- 
ing this  font.  The  default  is  to  overstrike  the  normal  font 

-j/+j  -j  indicates  that  xterm  should  do  jump  scrolling.  Normally,  text  is  scrolled 

one  line  at  a time;  this  option  allows  xterm  to  move  multiple  lines  at  a time  so 
that  it  doesn’t  fall  as  far  behind.  The  use  of  jump  scrolling  is  strongly  recom- 
mended since  it  makes  xterm  much  faster  when  scanning  through  large 
amounts  of  text.  The  VT100  escape  sequences  for  enabling  and  disabling 
smooth  scroll  and  the  Enable  Jump  Scroll  item  of  the  VT  Options  menu  can 
also  be  used  to  toggle  this  feature. 

The  + j option  specifies  that  xterm  not  do  jump  scrolling. 
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1/+1 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

-1  logs  xterm  input/output  into  a file  called  XtermLog.xxxx  where  jcjcxjc  rep- 
resents the  process  ID  number.  To  display  your  data,  turn  off  logging  using 
the  xterm  menu,  then  type  cat  XtermLog.xxxx  at  the  xterm  window 
prompt  and  the  output  file  is  sent  to  your  xterm  window.  Logging  allows  you 
to  keep  track  of  the  sequence  of  data  and  is  particularly  helpful  while  debug- 
ging code. 

+1  specifies  that  xterm  not  do  logging. 

(This  option  can  also  be  turned  on  and  off  from  the  VT  Options  menu, 
described  below.) 

If  file 

Specifies  the  file  in  which  the  data  is  written  to  rather  than  the  default  Xterm- 
Log.xxxx where  xxxx  is  the  process  identification  of  xterm  (the  file  is  created 
in  the  directory  that  xterm  is  started  in  or  the  home  directory  for  a login 
xterm).  If  file  begins  with  a “1  ”,  then  the  rest  of  the  string  is  assumed  to 
be  a command  to  be  executed  by  the  shell  and  a pipe  is  opened  to  the  process.  i 

ls/+ls 

-Is  indicates  that  the  shell  that  is  started  in  the  xterm  window  be  a login 
shell  (i.e.,  the  first  character  of  argv[0]  will  be  a dash,  indicating  to  the  shell 
that  it  should  read  the  user’s  .login  or  .profile). 

+ls  indicates  that  the  shell  that  is  started  should  not  be  a login  shell  (i.e.,  it 
will  be  a normal  “subshell.”) 

■mb/+mb 

-mb  turns  on  the  margin  bell.  Default  is  bell  off. 

+mb  indicates  that  the  margin  bell  should  not  be  rung. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 

below.) 

•me  milliseconds 

Specifies  the  maximum  time  between  multi-click  selections.  (Available  as  of 


■ms  color 

Release  4.) 

Sets  the  color  of  the  pointer.  The  default  is  to  use  the  foreground  color. 

■nb  number 

Sets  the  distance  at  which  the  margin  bell  rings  for  the  right  margin.  Default 
is  10  characters. 

-rw/+rw 

-rw  turns  on  the  reverse- wraparound  mode  that  allows  the  cursor  to  wrap- 
around from  the  leftmost  column  to  the  rightmost  column  of  the  previous  line. 
Allows  you  to  backspace  to  the  previous  line  and  overstrike  data  or  erase  data 
with  the  spacebar. 

+rw  indicates  that  reverse-wraparound  should  not  be  enabled. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 
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-Seen 


-s 


-sb/+sb 


-sf/+sf 


-si/+si 


-sk/+sk 


-si  number 
-t/+t 


Specifies  the  last  two  letters  of  the  name  of  a pseudo-terminal  to  use  in  slave 
mode,  plus  the  number  of  the  inherited  file  descriptor.  The  option  is  parsed 
“%c%c%d”.  This  allows  xterm  to  be  used  as  an  input  and  output  channel  for 
an  existing  program  and  is  sometimes  used  in  specialized  applications. 

Allows  xterm  to  scroll  asynchronously  with  the  display,  meaning  that  the 
screen  does  not  have  to  be  kept  completely  up  to  date  while  scrolling,  xterm 
saves  data  in  memory  which  is  displayed  later.  This  allows  xterm  to  run  fas- 
ter when  network  latencies  are  high  and  is  useful  when  running  xterm  across 
a large  internet  or  many  gateways. 

+s  indicates  that  xterm  should  scroll  synchronously. 

-sb  indicates  that  some  number  of  lines  that  are  scrolled  off  the  top  of  the 
window  should  be  saved  and  that  a scrollbar  should  be  displayed  at  startup  so 
those  lines  can  be  viewed. 

+sb  indicates  that  a scrollbar  should  not  be  displayed  at  startup. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

-sf  indicates  that  the  Sun  function  key  escape  codes  should  be  generated  for 
function  keys. 

+sb  indicates  that  the  standard  escape  codes  should  be  generated  for  function 
keys.  This  is  the  default. 

-si  disables  repositioning  the  cursor  at  the  bottom  of  the  scroll  region  when 
the  process  sends  output. 

+si  indicates  that  the  cursor  should  be  repositioned  at  the  bottom  of  the 
scroll  region  on  output. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

-sk  causes  the  cursor  to  be  repositioned  at  the  bottom  of  the  scroll  region 
when  a key  is  pressed. 

+sk  indicates  that  pressing  a key  while  using  the  scrollbar  should  not  cause 
the  cursor  to  be  repositioned  at  the  bottom  of  the  scroll  region. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

Specifies  the  maximum  number  of  lines  to  be  saved  that  are  scrolled  off  the 
top  of  the  window.  Default  is  64  lines. 

-t  causes  the  startup  xterm  window  to  be  the  Tektronix  window  rather  than 
the  VT102  window. 

+t  causes  the  startup  window  to  be  the  VT102  window.  This  is  the  default. 
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-tm  string  Specifies  a series  of  terminal  setting  keywords  followed  by  the  characters  that 
should  be  bound  to  those  functions,  similar  to  the  stty  program.  (In  Release  3, 
this  is  ignored  when  -L  is  given  since  getty  resets  the  terminal.  The  -L 
option  is  not  supported  in  Release  4.)  Allowable  keywords  include:  intr,  quit, 
erase,  kill,  eof,  eol,  swtch,  start,  stop,  brk,  susp,  dsusp,  rpmt,  flush,  weras,  and 
lnext.  Control  characters  may  be  specified  as  "char  (e.g.,  "c  or  "u),  and "?  may 
be  used  to  indicate  delete. 

-tn  name  Specifies  the  name  of  the  terminal  type  to  be  set  in  the  TERM  environment 
variable.  This  terminal  type  must  exist  in  the  termcap( 5)  database  and  should 
have  lift  and  coif  entries. 


-ut/+ub 


-vb/+vb 


-wf /+wf 


-ut  indicates  that  xterm  shouldn’t  write  a record  into  the  the  system  log  file 
letc/utmp. 


+ut  indicates  that  xterm  should  write  a record  into  the  system  log  file 
/etc/utmp. 


-vb  causes  your  terminal  window  to  flash  whenever  an  event  occurs  that 
would  ordinarily  cause  your  terminal  bell  to  ring. 

+vb  indicates  that  a visual  bell  should  not  be  used. 

(This  option  can  be  turned  on  and  off  from  the  Main  Options  menu,  described 
below.) 

-wf  indicates  that  xterm  should  wait  for  the  window  to  be  mapped  the  first 
time  before  starting  the  subprocess  so  that  the  initial  terminal  size  settings 
and  environment  variables  are  correct.  It  is  the  application’s  responsibility  to 
catch  subsequent  terminal  size  changes. 

+wf  indicates  that  xterm  should  not  wait  before  starting  the  subprocess. 


The  following  X Toolkit  options  are  commonly  used  with  xterm : 


-geometry  geometry 

xterm  takes  this  geometry  specification  for  the  VT102  window.  The  -geom- 
etry option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a con- 
flicting option  that  begins  with  “g.”  The  argument  to  the  geometry  option 
( geometry ) is  referred  to  as  a “standard  geometry  string,”  and  has  the  form 
widthxheight±xoff±yoff. 

-display  [host] : serverf . screen] 

By  default,  xterm  obtains  the  host,  server,  and  screen  to  use  from  the  environ- 
ment variable  DISPLAY.  However,  you  can  also  specify  them  using  the 
-display  option,  host  specifies  which  machine  to  create  the  window  on, 
server  specifies  the  server  number,  and  screen  specifies  the  screen  num- 
ber. For  example, 

xterm  -display  your node: 0.1 
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specifies  that  an  xterm  be  created  on  screen  1 of  server  0 on  the  machine 
your_node.  If  the  host  is  omitted,  the  local  machine  is  assumed.  If  the 
screen  is  omitted,  screen  0 is  assumed;  the  server  and  colon  (:)  are  necessary 
in  all  cases. 


-bd  color  Sets  the  color  of  the  border.  Default  of  the  highlighted  border  is  black. 
Default  of  the  unhighlighted  border  is  gray. 

-bg  col  or  Sets  the  background  color  of  the  xterm  window.  Default  is  white. 

-bw  pixels  Specifies  the  width  of  the  xterm  window  border  in  pixels.  Default  is  one 
pixel. 


-fg  color  Sets  the  color  of  the  text  (foreground).  Default  is  black. 

-fn  font  Uses  the  specified  font  instead  of  the  default  font  (fixed).  You  can  use  any 

fixed-width  font 


-iconic  Causes  xterm  to  display  an  xterm  icon  rather  than  an  xterm  window  when  it 
starts  up. 

-name  name  Specifies  the  application  name  under  which  resources  are  to  be  obtained, 
rather  than  the  default  executable  filename,  name  should  not  contain  or 
characters. 


-title  string 

Specifies  the  window  title  string,  which  may  be  displayed  by  window  manag- 
ers if  the  user  so  chooses.  The  default  title  is  the  command  line  specified 
after  the  -e  option,  if  any,  otherwise  the  application  name. 

-rv  Reverses  the  foreground  and  background  colors. 

(This  option  can  be  turned  on  and  off  from  the  VT  Options  menu,  described 
below.) 

-xrm  resourcestring 

Specifies  a resource  string  to  be  used  with  this  instance  of  the  application. 
This  is  especially  useful  for  setting  resources  that  do  not  have  command  line 
option  equivalents. 

The  following  command  line  arguments  are  provided  for  compatibility  with  older  versions 
(prior  to  Release  3).  They  may  not  be  supported  in  the  next  release  as  the  X Toolkit  provides 
standard  options  that  accomplish  most  of  the  same  tasks.  The  -L  option  has  been  eliminated  in 
Release  4. 

-L  Indicates  that  xterm  is  being  started  by  init.  In  this  mode,  xterm  does  not  try 

to  allocate  a new  pseudo-terminal  as  init  has  already  done  so.  (xterm 
presumes  that  its  file  descriptors  are  already  open  on  a slave  pseudo-termi- 
nal.) In  addition,  the  system  program  getty  is  run  rather  than  the  user’s  shell. 
This  option  is  only  used  by  init. 
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This  option  has  been  superceded  by  the  xdm  program.  Furthermore,  -L 
should  never  be  specified  by  users  when  starting  terminal  windows.  This 
option  has  been  eliminated  in  Release  4. 

% geometry  Specifies  the  preferred  size  and  location  of  the  Tektronix  window.  It  is  short- 
hand for  specifying  the  tekGeometry  resource. 


# geometry 


-n  string 


-r 


Specifies  the  preferred  position  of  the  icon.  It  is  shorthand  for  specifying  the 
iconGeometry  resource.  The  width  and  height  values  of  the  geometry 
string  are  optional. 

Specifies  the  icon  name  for  the  xterm  window.  It  is  shorthand  for  specifying 
the  *iconName  resource.  Note  that  this  is  not  equivalent  to  the  Toolkit 
option  -name.  The  default  icon  name  is  the  name  of  a program  run  with  the 
-e  option,  if  any,  otherwise  the  application  name. 

Indicates  that  reverse  video  should  be  simulated  by  swapping  the  foreground 
and  background  colors.  It  is  equivalent  to  -rv. 


-w  pixels  Specifies  the  width  in  pixels  of  the  border  surrounding  the  window.  It  is 
equivalent  to  -bw. 

-T  string  Specifies  the  title  for  the  xterm  window.  It  is  equivalent  to  -title. 

Resources 

The  program  understands  all  of  the  core  X Toolkit  resource  names  and  classes  as  well  as: 

iconGeometry  (class  IconGeometry) 

Specifies  the  preferred  size  and  position  of  the  application  when  iconified.  It 
is  not  necessarily  obeyed  by  all  window  managers. 

termName  (class  TermName) 

Specifies  the  terminal  type  name  to  be  set  in  the  TERM  environment  variable. 


title  (class  Title) 

Specifies  a string  that  may  be  used  by  the  window  manager  when  displaying 
this  application. 


ttyModes  (class  TtyModes) 

Specifies  a string  containing  terminal  setting  keywords  and  the  characters  to 
which  they  may  be  bound.  (In  Release  3,  this  resource  is  ignored  when  -L  is 
given  since  getty  resets  the  terminal.  The  -L  option  has  been  eliminated  in 
Release  4.)  Allowable  keywords  include:  intr,  quit,  erase,  kill,  eof,  eol, 
swtch,  start,  stop,  brk,  susp,  dsusp,  rpmt,  flush,  weras,  and  lnext.  Control 
characters  may  be  specified  as  * char  (e.g.,  ~c  or  ~u),  and  *?  may  be  used  to 
indicate  delete.  This  is  very  useful  for  overriding  the  default  terminal  settings 
without  having  to  do  an  stty  every  time  an  xterm  is  started. 


utmplnhibit  (class  Utmplnhibit) 

Specifies  whether  or  not  xterm  should  try  to  record  the  user’s  terminal  in 
/etc/utmp. 
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sunFunctionKeys  (class  SunFunctionKeys) 

Specifics  whether  or  not  Sun  Function  Key  escape  codes  should  be  generated 
for  function  keys  instead  of  standard  escape  sequences. 

The  following  resources  are  specified  as  part  of  the  vt  1 0 0 widget  (class  VT1 0 0): 

allowSendEvents  (class  AllowSendEvents) 

Specifies  whether  or  not  synthetic  key  and  button  events  (generated  using  the 
X protocol  SendEvent  request)  should  be  interpreted  or  discarded.  The 
default  is  false  meaning  they  are  discarded.  Note  that  allowing  such  events 
creates  a very  large  security  hole.  (Available  as  of  Release  4.) 

alwaysHighlight  (class  AlwaysHighlight) 

Specifies  whether  or  not  xterm  should  always  display  a highlighted  text  cur- 
sor. By  default,  a hollow  text  cursor  is  displayed  whenever  the  pointer  moves 
out  of  the  window  or  the  window  loses  the  input  focus. 

boldFont  (class  Font) 

Specifies  the  name  of  the  bold  font  to  use  instead  of  overstriking  the  normal 
font. 

cl32  (class  C132) 

Specifies  whether  or  not  the  VT102  DECCOLM  escape  sequence  should  be 
honored.  The  default  is  false. 

charClass  (class  CharClass) 

Specifies  comma-separated  lists  of  character  class  bindings  of  the  form 
[low-]high:  value.  These  are  used  in  determining  which  sets  of  characters 
should  be  treated  the  same  when  doing  cut  and  paste.  See  “Character 
Classes”  below. 

curses  (class  Curses ) 

Specifies  whether  or  not  the  last  column  bug  in  the  cursor  should  be  worked 
around.  The  default  is  false. 

background  (class  Background) 

Specifies  the  color  to  use  for  the  background  of  the  window.  The  default  is 
white. 

foreground  (class  Foreground) 

Specifies  the  color  to  use  for  displaying  text  in  the  window.  Setting  the  class 
name  instead  of  the  instance  name  is  an  easy  way  to  have  everything  that 
would  normally  appear  in  the  “text”  color  change  color.  The  default  is  black. 

cursorColor  (class  Foreground) 

Specifies  the  color  to  use  for  the  text  cursor.  The  default  is  black. 

eightBitlnput  (class  EightBitlnput) 

Specifies  whether  or  not  eight-bit  characters  should  be  accepted.  The  default 
is  true.  (Available  as  of  Release  4.) 
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font  (class  Font) 

Specifies  the  name  of  the  normal  font. 

fontl  (class  Fontl) 

Specifies  the  name  of  the  first  alternate  font.  This  font  is  toggled  using  the 
Tiny  menu  item  on  the  VT  Fonts  menu.  (Available  as  of  Release  4.) 

f ont2  (class  Font2) 

Specifies  the  name  of  the  second  alternate  font.  This  font  is  toggled  using  the 
Small  menu  item  on  the  VT  Fonts  menu.  (Available  as  of  Release  4.) 

f ont3  (class  Font3) 

Specifies  the  name  of  the  third  alternate  font.  This  font  is  toggled  using  the 
Medium  menu  item  on  the  VT  Fonts  menu.  (Available  as  of  Release  4.) 

font  4 (class  Font  4) 

Specifies  the  name  of  the  fourth  alternate  font.  This  font  is  toggled  using  the 
Large  menu  item  on  the  VT  Fonts  menu.  (Available  as  of  Release  4.) 

geometry  (class  Geometry) 

Specifies  the  preferred  size  and  position  of  the  VT102  window. 

internalBorder  (class  BorderWidth) 

Specifies  the  number  of  pixels  between  the  characters  and  the  window  border. 
The  default  is  2. 

jumpScroll  (class  JumpScroll) 

Specifies  whether  or  not  jump  scroll  should  be  used.  The  default  is  true. 

logFile  (class  Logfile) 

Specifies  the  name  of  the  file  to  which  a terminal  session  is  logged.  The 
default  is  XtermLog . xxxx  (where  xxxx  is  the  process  ID  of  xterm). 

logging  (class  Logging) 

Specifies  whether  or  not  a terminal  session  should  be  logged.  The  default  is 
false. 


loglnhibit  (class  Loglnhibit ) 

Specifies  whether  or  not  terminal  session  logging  should  be  inhibited.  The 
default  is  false. 


loginShell  (class  LoginShell) 

Specifies  whether  or  not  the  shell  to  be  run  in  the  window  should  be  started  as 
a login  shell.  The  default  is  false. 

marginBell  (class  MarginBell) 

Specifies  whether  or  not  the  bell  should  be  run  when  the  user  types  near  the 
right  margin.  The  default  is  false. 

multiClickTime  (class  MultiClickTime) 

Specifies  the  maximum  time  in  milliseconds  between  multi-clock  select 
events.  The  default  is  250  milliseconds.  (Available  as  of  Release  4.) 
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multiScroll  (class  MultiScroll) 

Specifies  whether  or  not  scrolling  should  be  done  asynchronously.  The 
default  is  false. 

nMarginBell  (class  Column) 

Specifies  the  number  of  characters  from  the  right  margin  at  which  the  margin 
bell  should  be  run,  when  enabled. 

pointerColor  (class  Foreground) 

Specifies  the  color  of  the  pointer.  The  default  is  XtDe  fault  Foreground 
color. 

pointerColorBackground  (class  Background) 

Specifies  the  background  color  of  the  pointer.  The  default  is  xtDefault- 
Background  color.  (Available  as  of  Release  4.) 

pointerShape  (class  Cursor ) 

Specifies  the  name  of  the  shape  of  the  pointer.  The  default  is  “xterm.” 

reverseVideo  (class  ReverseVideo) 

Specifies  whether  or  not  reverse  video  should  be  simulated.  The  default  is 
false. 

reverseWrap  (class  ReverseWrap) 

Specifies  whether  or  not  reverse-wraparound  should  be  enabled.  The  default 
is  false. 

saveLines  (class  SaveLines) 

Specifies  the  number  of  lines  to  save  beyond  the  top  of  the  screen  when  a 
scrollbar  is  turned  on.  The  default  is  64. 

scrollBar  (class  ScrollBar) 

Specifies  whether  or  not  the  scrollbar  should  be  displayed.  The  default  is 
false. 

scrolllnput  (class  ScrollCond) 

Specifies  whether  or  not  output  to  the  terminal  should  automatically  cause  the 
scrollbar  to  go  to  the  bottom  of  the  scrolling  region.  The  default  is  true. 

scrollKey  (class  ScrollCond) 

Specifies  whether  or  not  pressing  a key  should  automatically  cause  the 
scrollbar  to  go  to  the  bottom  of  the  scrolling  region.  The  default  is  false. 

scrollLines  (class  ScrollLines) 

Specifies  the  number  of  lines  that  the  scroll-back  and  scroll-forw 
actions  should  use  as  a default.  The  default  value  is  1.  (Available  as  of 
Release  4.)  (See  “Actions.”) 

signallnhibit  (class  Signallnhibit ) 

Specifies  whether  or  not  the  entries  in  the  Main  Options  menu  for  sending  sig- 
nals to  xterm  should  be  disallowed.  The  default  is  false. 
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tekGeometry  (class  Geometry) 

Specifies  the  preferred  size  and  position  of  the  Tektronix  window. 

teklnhibit  (class  Teklnhibit) 

Specifies  whether  or  not  Tektronix  mode  should  be  disallowed.  The  default  is 
false. 

tekSmall  (class  TekSmall) 

Specifies  whether  or  not  the  Tektronix  mode  window  should  start  in  its  smal- 
lest size  if  no  explicit  geometry  is  given.  This  is  useful  when  running  xterm 
on  displays  with  small  screens.  The  default  is  false.  (Available  as  of  Release 
4.) 

tekStartup  (class  TekStartup) 

Specifies  whether  or  not  x term  should  start  up  in  Tektronix  mode.  The  default 
is  false. 

titelnhibit  (class  Titelnhibit) 

Specifies  whether  or  not  xterm  should  remove  ti  or  te  termcap  entries  (used 
to  switch  between  alternate  screens  on  startup  of  many  screen-oriented  pro- 
grams) from  the  TERMCAP  string. 

translations  (class  Translations) 

Specifies  the  key  and  button  bindings  for  menus,  selections,  “programmed 
strings,”  etc.  See  “Actions”  below. 

visualBell  (class  VisualBell) 

Specifies  whether  or  not  a visible  bell  (i.e.,  flashing)  should  be  used  instead  of 
an  audible  bell  when  Control-G  is  received.  The  default  is  false. 

waitForMap  (class  WaitForMap) 

Specifies  whether  or  not  xterm  should  wait  for  the  initial  window  map  before 
starting  the  subprocess.  The  default  is  false.  (Available  as  of  Release  4.) 

The  following  resources  are  specified  as  part  of  the  tek4014  widget  (class  Tek4  014): 
width  (class  width) 

Specifies  the  width  of  the  Tektronix  window  in  pixels, 
height  (class  Height) 

Specifies  the  height  of  the  Tektronix  window  in  pixels, 
f ontLarge  (class  Font) 

Specifies  the  large  font  to  use  in  the  Tektronix  window.  (Available  as  of 
Release  4.)  This  font  is  toggled  using  the  Large  Characters  item  on  the  Tek 
Options  menu. 

f ont2  (class  Font) 

Specifies  font  number  2 to  use  in  the  Tektronix  window.  (Available  as  of 
Release  4.)  This  font  is  toggled  using  the  #2  Size  Characters  item  on  the  Tek 
Options  menu. 
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font3  (class  Font) 

Specifies  font  number  3 font  to  use  in  the  Tektronix  window.  (Available  as  of 
Release  4.)  This  font  is  toggled  using  the  #3  Size  Characters  item  on  the  Tek 
Options  menu. 

fontSmall  (class  Font) 

Specifies  the  small  font  to  use  in  the  Tektronix  window.  (Available  as  of 
Release  4.)  This  font  is  toggled  using  the  Small  Characters  item  on  the  Tek 
Options  menu. 

As  of  Release  4,  the  resources  that  can  be  specified  for  the  various  menus  are  described  in  the 
documentation  for  the  Athena  SimpleMenu  widget.  The  name  and  classes  of  the  entries  in  each 
of  the  menus  are  listed  below. 

The  mainMenu  (title  Main  Options)  has  the  following  entries: 

securekbd  (class  SmeBSB) 

Invokes  the  secure  ()  action. 

allowsends  (class  SmeBSB) 

Invokes  the  allow-send-events  (toggle)  action. 

logging  (class  SmeBSB) 

Invokes  the  set -logging  (toggle)  action. 

redraw  (class  SmeBSB) 

Invokes  the  redraw  ( ) action. 

linel  (class  SmeLine) 

A separator. 

suspend  (class  SmeBSB) 

Invokes  the  send-signal  (suspend)  action  on  systems  that  support  job 
control. 

continue  (class  SmeBSB) 

Invokes  the  send-signal  (cont)  action  on  systems  that  support  job  con- 
trol. 

interrupt  (class  SmeBSB) 

Invokes  the  send-signal  (int)  action. 

hangup  (class  SmeBSB) 

Invokes  the  send-signal  (hup)  action. 

terminate  (class  SmeBSB) 

Invokes  the  send-signal  (term)  action. 

kill  (class  SmeBSB) 

Invokes  the  send-signal  (kill)  action. 

Iine2  (class  SmeLine) 

A separator. 
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quit  (class  SmeBSB) 

Invokes  the  quit  ( ) action. 

The  vtMenu  (title  VT  Options)  has  the  following  entries: 

scrollbar  (class  SmeBSB) 

Invokes  the  set-scrollbar  (toggle)  action. 

jumpscroll  (class  SmeBSB) 

Invokes  the  set- jumpscroll  (toggle)  action. 

reversevideo  (class  SmeBSB) 

Invokes  the  set-reverse-video  (toggle)  action. 

autowrap  (class  SmeBSB) 

Invokes  the  set-autowrap  (toggle)  action. 

reversewrap  (class  SmeBSB) 

Invokes  the  set-reversewrap  (toggle)  action. 

autolinefeed  (class  SmeBSB) 

Invokes  the  set-autolinefeed  (toggle)  action. 

appcursor  (class  SmeBSB) 

Invokes  the  set-appcursor  (toggle)  action. 

appkeypad  (class  SmeBSB) 

Invokes  the  set-appkeypad  (toggle)  action. 

scrollkey  (class  SmeBSB) 

Invokes  the  set-scroll-on-key  (toggle)  action. 

scrollttyoutput  (class  SmeBSB) 

Invokes  the  set-scroll-on-tty-output  (toggle)  action. 

allowl32  (class  SmeBSB) 

Invokes  the  set-allowl32  (toggle)  action. 

cursesemul  (class  SmeBSB) 

Invokes  the  set-cur sesemul  (toggle)  action. 

visualbell  (class  SmeBSB) 

Invokes  the  set-visualbell  (toggle)  action. 

marginbell  (class  SmeBSB) 

Invokes  the  set-marginbell  (toggle)  action. 

altscreen  (class  SmeBSB) 

This  entry  is  currently  disabled. 

linel  (class  SmeLine) 

A separator. 

softreset  (class  SmeBSB) 

Invokes  the  soft-reset  ()  action. 
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hardreset  (class  SmeBSB) 

Invokes  the  hard- reset  ( ) action. 

Iine2  (class  SmeLine) 

A separator. 

tekshow  (class  SmeBSB) 

Invokes  the  set-visibility  (tek,  toggle)  action. 

tekmode  (class  SmeBSB) 

Invokes  the  set-terminal-type  (tek)  action. 

vthide  (class  SmeBSB) 

Invokes  the  set -visibility  (vt , of  f ) action. 

The  f ontMenu  (title  VT  Fonts)  has  the  following  entries: 

f ontdef  ault  (class  SmeBSB) 

Invokes  the  set-vt-font  (d)  action. 

fontl  (class  SmeBSB) 

Invokes  the  set-vt-font  (1)  action. 

font2  (class  SmeBSB) 

Invokes  the  set-vt-font  (2)  action. 

font3  (class  SmeBSB) 

Invokes  the  set-vt-font  (3)  action. 

font 4 (class  SmeBSB) 

Invokes  the  set-vt-font  (4)  action. 

fontescape  (class  SmeBSB) 

Invokes  the  set-vt-font  (e)  action. 

fontsel  (class  SmeBSB) 

Invokes  the  set-vt-font  (s)  action. 

The  tekMenu  (title  Tek  Options)  has  the  following  entries: 

tektextlarge  (class  SmeBSB) 

Invokes  the  set-tek-text  (1)  action. 

tektext2  (class  SmeBSB) 

Invokes  the  set-tek-text  (2)  action. 

tektext3  (class  SmeBSB) 

Invokes  the  set-tek-text  (3)  action. 

tektextsmall  (class  SmeBSB) 

Invokes  the  set-tek-text  (s)  action. 

linel  (class  SmeLine) 

A separator. 
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tekpage  (class  SmeBSB) 

Invokes  the  tek-page  ( ) action. 

tekreset  (class  SmeBSB) 

Invokes  the  tek-reset  ( ) action. 

tekcopy  (class  SmeBSB) 

Invokes  the  tek-copy  ( ) action. 

Iine2  (class  SmeLine) 

A separator. 

vtshow  (class  SmeBSB) 

Invokes  the  set-visibility  (vt,  toggle)  action. 

vtmode  (class  SmeBSB) 

Invokes  the  set-terminal-type  (vt)  action. 


tekhide  (class  SmeBSB) 

Invokes  the  set-visibility  (tek,  toggle)  action. 

The  following  resources  are  useful  when  specified  for  the  Athena  Scrollbar  widget  (scroll- 
Bar,  class  ScrollBar): 

thickness  (class  Thickness) 

Specifies  the  width  in  pixels  of  the  scrollbar. 

background  (class  Background) 

Specifies  the  color  to  use  for  the  background  of  the  scrollbar. 

foreground  (class  Foreground) 

Specifies  the  color  to  use  for  the  foreground  of  the  scrollbar.  The  “thumb” 
of  the  scrollbar  is  a simple  checkerboard  pattern  alternating  pixels  for  fore- 
ground and  background  color. 

The  Release  3 version  of  x term  uses  the  menu  widget,  which  accepts  the  following  resources: 
menuBorder  (class  MenuBorder) 

Specifies  the  size  in  pixels  of  the  border  surrounding  menus.  The  default  is  2. 


menuFont  (class  Font) 

Specifies  the  name  of  the  font  to  use  for  displaying  menu  items. 
menuPad  (class  MenuP ad) 

Specifies  the  number  of  pixels  between  menu  items  and  the  menu  border.  The 
default  is  3. 


Emulations 

The  VT102  emulation  is  fairly  complete,  but  does  not  support  the  blinking  character  attribute 
nor  the  double-wide  and  double-size  character  sets,  termcap  entries  that  work  with  xterm 
include  “xterm”,  “vtl02”,  “vtlOO”  and  “ansi”,  xterm  automatically  searches  the  termcap 
file  in  this  order  for  these  entries  and  then  sets  the  TERM  and  the  TERMCAP  environment  vari- 
ables. Note  that  the  “xterm”  termcap  entry  distributed  with  X is  not  automatically  installed. 
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You  must  add  it  to  letc/termcap  yourself. 

Many  of  the  special  xterm  features  (like  logging)  may  be  modified  under  program  control 
through  a set  of  escape  sequences  different  from  the  standard  VT102  escape  sequences.  (See 
Appendix  E , xterm  Control  Sequences,  in  this  guide.) 

The  Tektronix  4014  emulation  is  also  fairly  good.  Four  different  font  sizes  and  five  different 
line  types  are  supported.  The  Tektronix  text  and  graphics  commands  are  recorded  internally  by 
xterm  and  may  be  written  to  a file  by  sending  the  COPY  escape  sequence  (or  through  the  Tek- 
tronix menu;  see  below).  The  name  of  the  file  will  be  “copy yy-MM-dd.hh  :mm:  ss”,  where 
yy,  MM,  dd,  hh,  mm  and  ss  are  the  year,  month,  day,  hour,  minute  and  second  when  the  COPY 
was  performed  (the  file  is  created  in  the  directory  xterm  is  started  in,  or  the  home  directory  for  a 
login  xterm). 

Pointer  Usage 

Once  the  VT102  window  is  created,  xterm  allows  you  to  select  text  and  copy  it  within  the  same 
or  other  windows. 

The  selection  functions  are  invoked  when  the  pointer  buttons  are  used  with  no  modifiers,  and 
when  they  are  used  with  the  Shift  key.  The  assignment  of  the  functions  described  below  to 
keys  and  buttons  may  be  changed  through  the  resource  database;  see  “Actions”  below. 

Pointer  button  one  (usually  the  left)  is  used  to  save  text  into  the  cut  buffer.  Move  the  cursor  to 
the  beginning  of  the  text,  and  then  hold  the  button  down  while  moving  the  cursor  to  the  end  of 
the  region  and  release  the  button.  The  selected  text  is  highlighted  and  is  saved  in  the  global  cut 
buffer  and  made  the  PRIMARY  selection  when  the  button  is  released.  Double-clicking  selects 
by  words.  Triple-clicking  selects  by  lines.  Quadruple-clicking  goes  back  to  characters,  etc. 
Multiple-click  is  determined  by  the  time  from  button  up  to  button  down,  so  you  can  change  the 
selection  unit  in  the  middle  of  a selection.  If  the  key/button  bindings  specify  that  an  X selec- 
tion is  to  be  made,  xterm  will  leave  the  selected  text  highlighted  for  as  long  as  it  is  the  selection 
owner. 

Pointer  button  two  (usually  the  middle)  ‘types’  (pastes)  the  text  from  the  PRIMARY  selection,  if 
any,  otherwise  from  the  cut  buffer,  inserting  it  as  keyboard  input. 

Pointer  button  three  (usually  the  right)  extends  the  current  selection.  (You  can  swap  “right” 
and  “left”  everywhere  in  the  rest  of  this  paragraph.)  If  pressed  while  closer  to  the  right  edge  of 
the  selection  than  the  left,  it  extends/contracts  the  right  edge  of  the  selection.  If  you  contract 
the  selection  past  the  left  edge  of  the  selection,  xterm  assumes  you  really  meant  the  left  edge, 
restores  the  original  selection,  then  extends/contracts  the  left  edge  of  the  selection.  Extension 
starts  in  the  selection  unit  mode  that  the  last  selection  or  extension  was  performed  in;  you  can 
multiple-click  to  cycle  through  them. 

By  cutting  and  pasting  pieces  of  text  without  trailing  new  lines,  you  can  take  text  from  several 
places  in  different  windows  and  form  a command  to  the  shell,  for  example,  or  take  output  from 
a program  and  insert  it  into  your  favorite  editor.  Since  the  cut  buffer  is  globally  shared  among 
different  applications,  you  should  regard  it  as  a ‘file’  whose  contents  you  know.  The  terminal 
emulator  and  other  text  programs  should  be  treating  it  as  if  it  were  a text  file,  i.e.,  the  text  is  del- 
imited by  new  lines. 
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The  scroll  region  displays  the  position  and  amount  of  text  currently  showing  in  the  window 
(highlighted)  relative  to  the  amount  of  text  actually  saved.  As  more  text  is  saved  (up  to  the 
maximum),  the  size  of  the  highlighted  area  decreases. 

Clicking  button  one  with  the  pointer  in  the  scroll  region  moves  the  adjacent  line  to  the  top  of 
the  display  window. 

Clicking  button  three  moves  the  top  line  of  the  display  window  down  to  the  pointer  position. 

Clicking  button  two  moves  the  display  to  a position  in  the  saved  text  that  corresponds  to  the 
pointer’s  position  in  the  scrollbar. 

Unlike  the  VT102  window,  the  Tektronix  window  does  not  allow  the  copying  of  text.  It  does 
allow  Tektronix  GIN  mode,  and  in  this  mode  the  cursor  will  change  from  an  arrow  to  a cross. 
Pressing  any  key  will  send  that  key  and  the  current  coordinate  of  the  cross  cursor.  Pressing  but- 
ton one,  two,  or  three  will  return  the  letters  T,  ‘m’,  and  V,  respectively.  If  the  Shift  key  is 
pressed  when  a pointer  button  is  pressed,  the  corresponding  upper  case  letter  is  sent.  To  distin- 
guish a pointer  button  from  a key,  the  high  bit  of  the  character  is  set  (but  this  bit  is  normally 
stripped  unless  the  terminal  mode  is  RAW;  see  tty (4)  for  details). 

Menus 

The  Release  4 version  of  xterm  has  four  different  menus,  titled  Main  Options,  VT  Options,  Tek 
Options,  and  VT  Fonts.  The  first  three  menus  are  available  in  Release  3 under  the  names  xterm, 
Modes,  and  Tektronix.  The  VT  Fonts  menu  is  available  as  of  Release  4. 

Many  of  the  menu  items  have  been  also  been  renamed  in  Release  4;  however,  most  items  have 
not  changed  in  functionality.  The  following  sections  describe  the  items  available  on  the 
Release  3 and  4 menus.  In  the  sections  describing  the  various  menu  items,  if  an  item  has  sim- 
ply been  renamed,  the  Release  3 name  appears  in  parentheses  after  the  Release  4 name. 

Each  menu  pops  up  under  the  correct  combinations  of  key  and  button  presses.  Most  menus  are 
divided  into  two  sections,  separated  by  a horizontal  line.  The  top  portion  contains  various 
modes  that  can  be  specified.  A check  mark  appears  next  to  a mode  that  is  currently  active. 
Selecting  one  of  these  modes  toggles  its  state.  The  bottom  portion  contains  command  entries; 
selecting  one  of  these  performs  the  indicated  function.  The  menus  are  described  in  detail  in  the 
following  sections. 

Main  Options  Menu  (Release  3:  xterm  Menu) 

The  Main  Options  menu  (formerly  xterm)  is  displayed  when  the  Control  key  and  pointer  button 
one  are  simultaneously  pressed  in  an  xterm  window.  The  modes  section  contains  items  that 
apply  to  both  the  VT102  and  Tektronix  windows.  The  modes  can  also  be  set  by  command  line 
options  when  invoking  xterm , or  by  entries  in  a resource  startup  file  like  X resources  (see  Chap- 
ter 9,  Setting  Resources).  The  menu  selections  enable  you  to  change  your  mind  once  xterm  is 
running. 

All  of  the  commands  on  this  menu  (except  for  Redraw  Window)  send  a signal  that  is  intended  to 
affect  the  xterm  process  (Send  INT  Signal,  Send  TERM  Signal,  etc.).  Given  that  your  operating 
system  may  recognize  only  certain  signals,  every  menu  item  may  not  produce  the  intended 
function. 
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Four  of  these  commands  (Send  HUP  Signal,  Send  TERM  Signal,  Send  KILL  Signal,  and  Quit) 
send  signals  that  are  intended  to  terminate  the  xterm  window.  In  most  cases,  you  can  probably 
end  an  xterm  process  simply  by  typing  some  sequence  (such  as  Control-D  or  exit)  in  the  win- 
dow. Of  course,  the  menu  options  may  be  helpful  if  the  more  conventional  ways  of  killing  the 
window  fail. 

Main  Options  Menu  Mode  Toggles  (On/Off) 

Visual  Bell  Causes  your  terminal  window  to  flash  whenever  an  event  occurs  that 

would  ordinarily  cause  your  terminal  bell  to  ring.  This  item  appears 
on  the  equivalent  Release  3 menu  (the  xterm  menu)  only.  In  Release 
4,  it  has  been  renamed  Enable  Visual  Bell  and  moved  to  the  VT  Options 
menu. 

Secure  Keyboard  Ensures  that  all  keyboard  input  is  directed  only  to  xterm.  Used  when 
typing  in  passwords  or  other  sensitive  data  in  an  unsecure  environ- 
ment. (See  “Security”  later  in  this  reference  page.) 

Allow  SendEvents  (Release  4 only) 

Causes  synthetic  key  and  button  events  (generated  using  the  X proto- 
col SendEvent  request)  to  be  interpreted.  Note  that  allowing  such 
events  creates  a very  large  security  hole. 

Log  to  File  (Release  3:  Logging) 

Logs  xterm  input/output  into  a file  in  your  home  directory  called 
XtermLog.xxxxx  where  xxxxx  represents  the  process  ID  number  of  the 
xterm  process.  Logging  allows  you  to  keep  track  of  the  sequence  of 
data  and,  therefore,  is  particularly  helpful  while  debugging  code. 

To  display  the  data  contained  in  the  log  file,  at  the  xterm  window 
prompt,  type: 

mora  XtermLog . xxxxx 
The  output  file  is  sent  to  your  xterm  window. 

Be  sure  to  turn  Log  to  File  off  before  displaying  the  log  file  in  the 
xterm  window.  When  Log  to  File  is  on,  anything  in  the  window  is 
appended  to  the  end  of  the  log  file.  If  you  display  the  log  file  while 
logging  is  on,  you  will  get  into  a continuous  loop,  much  as  if  you 
typed  cat  * > file. 

To  find  out  the  exact  name  of  the  log  file,  list  the  contents  of  your 
home  directory,  looking  for  a log  file  with  an  appropriate  time  and 
date.  Note  that  if  you  turn  logging  on  in  multiple  xterm  windows, 
there  will  be  multiple  log  files. 

Main  Options  Menu  Commands 

Redraw  Window  (Release  3:  Redraw) 

Redraws  the  contents  of  the  window.  (If  you  are  using  the  uwm  win- 
dow manager,  you  can  also  do  this  with  the  Redraw  selection  of  the 
uwm  WindowOps  menu.  Or  you  can  refresh  the  entire  screen  with  the 
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xrefresh  client  or  the  Refresh  Screen  selection  of  the  WindowOps 
menu.  See  Appendix  B,  Using  the  uwm  Window  Manager.) 

Send  STOP  Signal  (Release  3:  Suspend  program) 

Suspends  a process  (sends  the  SIGTSTP  signal  to  the  process  group  of 
the  process  running  under  xterm , usually  the  shell).  If  your  system 
supports  job  control,  you  may  also  be  able  to  suspend  the  process  by 
typing  Control-Z.  If  your  system  does  not  support  job  control,  this 
menu  item  won’t  work  either. 

Send  CONT  Signal  (Release  3:  Continue  program) 

Continues  a process  that  has  been  suspended  (technically  speaking, 
this  menu  item  sends  the  SIGCONT  signal  to  the  process  group  of  the 
process  running  under  xterm , usually  the  shell).  The  Send  CONT  Sig- 
nals item  is  especially  useful  on  systems  with  job  control  if  you  acci- 
dentally type  Control-Z  and  suspend  a process. 

Send  INT  Signal  (Release  3:  Interrupt  program) 

Interrupts  a process  (sends  the  SIGINT  signal  to  the  process  group  of 
the  process  running  under  xterm , usually  the  shell). 

Send  HUP  Signal  (Release  3:  Hangup  program) 

Hangs  up  the  process  (sends  the  SIGHUP  signal  to  the  process  group  of 
the  process  running  under  xterm , usually  the  shell).  This  usually  ends 
up  killing  the  x term  process,  and  the  window  disappears  from  the 
screen. 

Send  TERM  Signal  (Release  3:  Terminate  program) 

Terminates  the  process  (sends  the  SIGTERM  signal  to  the  process 
group  of  the  process  running  under  xterm,  usually  the  shell).  This 
usually  ends  up  killing  the  xterm  process,  and  the  window  disappears 
from  the  screen. 

Send  KILL  Signal  (Release  3:  Kill  program) 

Kills  the  process  (sends  the  SIGKILL  signal  to  the  process  group  of  the 
process  running  under  xterm,  usually  the  shell).  This  ends  up  killing 
the  xterm  process,  and  the  window  disappears  from  the  screen. 

Quit  Like  Send  HUP  Signal,  Quit  sends  the  SIGHUP  signal  to  the  process 

group  of  the  process  running  under  xterm,  usually  the  shell.  This 
usually  ends  up  killing  the  xterm  process,  and  the  window  disappears 
from  the  screen. 

Quit  is  separated  from  the  earlier  commands  by  a horizontal  line,  so 
it’s  easier  to  point  at.  Sending  a SIGHUP  signal  with  Quit  is  also 
slightly  more  gentle  to  the  system  than  using  Send  KILL  Signal. 

See  signal(3C ) in  the  UNIX  Programmer’ s Manual  for  more  information  on  what  each  signal 

does. 
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VT  Options  Menu  (Release  3:  Modes  Menu) 

The  VT  Options  menu  (formerly  Modes)  menu  sets  various  modes  in  the  VT102  emulation  and 
is  displayed  when  the  Control  key  and  pointer  button  two  are  pressed  in  the  VT102  window. 

In  the  command  section  of  this  menu,  the  soft  reset  entry  will  reset  scroll  regions.  This  can  be 
convenient  when  some  program  has  left  the  scroll  regions  set  incorrectly  (often  a problem  when 
using  VMS  or  TOPS-20).  The  full  reset  entry  will  clear  the  screen,  reset  tabs  to  every  eight 
columns,  and  reset  the  terminal  modes  (such  as  wrap  and  smooth  scroll)  to  their  initial  states 
just  after  xterm  has  finish  processing  the  command  line  options. 

VT  Options  Menu  Mode  Toggles  (On/Off) 

Most  of  these  modes  can  also  be  set  by  command  line  options  when  invoking  xterm , or  by 
entries  in  a resource  startup  file  like  Xresources  (see  Chapter  9,  Setting  Resources).  The  menu 
selections  enable  you  to  change  your  mind  once  xterm  is  running. 

Enable  Scrollbar  (Release  3:  Scrollbar) 

Causes  a scrollbar  to  appear  on  the  left-hand  side  of  the  xterm  win- 
dow. Off  by  default. 

Enable  Jump  Scroll  (Release  3:  Jump  Scroll) 

Causes  the  window  to  move  text  several  lines  at  a time  rather  than  line 
by  line.  On  by  default. 

Enable  Reverse  Video  (Release  3:  Reverse  Video) 

Reverses  the  foreground  and  background  colors.  Off  by  default. 

Enable  Auto  Wraparound  (Release  3:  Auto  Wraparound) 

Wraps  the  text  or  data  to  the  next  line  automatically  when  the  cursor 
reaches  the  window  border  on  input.  On  by  default. 

Enable  Reverse  Wraparound  (Release  3:  Reverse  Wraparound) 

Allows  the  cursor  to  wrap  around  from  the  leftmost  column  to  the 
rightmost  column  of  the  previous  line.  Allows  you  to  backspace  to  the 
previous  line  and  overstrike  data  or  erase  data  with  the  space  bar.  Off 
by  default. 

Enable  Auto  Linefeed  (Release  3:  Auto  Linefeed) 

Generates  a linefeed  automatically.  This  is  useful  if  you  are  using  a 
program  that  generates  a carriage  return  without  dropping  down  a line 
on  your  screen.  Off  by  default.  (This  option  is  usually  not  needed  on 
UNIX  systems.) 

Enable  Application  Cursor  Keys  (Release  3:  Application  Cursor  Mode) 

Generates  ANSI  escape  sequences  rather  than  standard  cursor  move- 
ment when  you  use  the  arrow  keys.  This  option  may  be  useful  when 
working  with  certain  applications.  Off  by  default. 

The  following  table  lists  the  ANSI  characters  generated  by  application 
cursors. 
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Cursor  Key 
(Arrow) 

Reset 

(Cursor) 

Set 

(Application) 

Up 

ESC  [A 

ESCO  A 

Down 

ESC  [ B 

ESC  OB 

Right 

ESC  [ C 

ESC  0 C 

Left 

ESC  [ D 

ESCOD 

Enable  Application  Keypad  (Release  3:  Application  Keypad  Mode) 

Generates  a control  function  rather  than  a numeric  character  when  you 
use  the  numeric  keypad.  Off  by  default. 


Scroll  to  Bottom  on  Key  Press 

Indicates  that  pressing  a key  while  using  the  scrollbar  causes  the  cur- 
sor to  be  repositioned  at  the  bottom  of  the  scroll  region.  For  example, 
if  you  have  scrolled  up  the  window  to  see  past  history,  as  soon  as  you 
begin  typing  your  next  command  the  cursor  jumps  to  the  bottom  of  the 
screen.  Off  by  default. 


Scroll  to  Bottom  on  Tty  Output 

Indicates  that  receiving  output  to  the  window  (or  pressing  a key,  if 
stty  echo  has  been  specified),  while  using  the  scrollbar  causes  the 
cursor  to  be  repositioned  at  the  bottom  of  the  scroll  region.  In  Release 
4,  on  by  default.  (In  Release  3,  off  by  default;  on  automatically  if  the 
window  has  a scrollbar.)  This  mode  can  be  toggled  off,  but  is  gener- 
ally desirable  to  have. 


Allow  80/132  Column  Switching  (Release  3:  Allow  80/132  switching) 

Allows  xterm  to  recognize  the  DECCOLM  escape  sequence,  which 
switches  the  terminal  between  80  and  132-column  mode.  The  DEC- 
COLM escape  sequence  can  be  included  in  a program  (such  as  a 
spreadsheet)  to  allow  the  program  to  display  in  132-column  format. 
See  Appendix  E,  xterm  Control  Sequences , for  more  information.  Off 
by  default. 


Enable  Curses  Emulation  (Release  3:  Curses  Emulation) 

Enables  the  curses  fix.  Several  programs  that  use  the  curses  cursor 
motion  package  have  some  difficulties  with  VT  102-compatible  termi- 
nals. The  bug  occurs  when  you  run  the  more  program  on  a file  con- 
taining a line  that  is  exactly  the  width  of  the  window  and  that  is  fol- 
lowed by  a line  beginning  with  a tab.  The  leading  tabs  may  disappear. 
This  mode  causes  the  tabs  to  be  displayed  correctly.  Off  by  default. 


Enable  Visual  Bell  Causes  your  terminal  window  to  flash  whenever  an  event  occurs  that 
would  ordinarily  cause  your  terminal  bell  to  ring.  This  item  appears  as 
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Visual  Bell  on  the  Release  3 xterm  menu.  In  Release  4,  it  has  been 
renamed  Enable  Visual  Bell  and  moved  to  the  VT  Options  menu. 

Enable  Margin  Bell  (Release  3:  Margin  Bell) 

Turns  on  the  margin  bell.  Off  by  default. 

Tek  Window  Showing  Shows  the  current  contents  of  the  Tektronix  window;  you  cannot  input 
to  that  window  until  you  choose  Switch  to  Tek  Mode.  Off  by  default. 
This  item  is  a mode  toggle  on  the  equivalent  Release  3 menu  (Modes). 
In 

Release  4,  it  has  been  renamed  and  moved  to  the  commands  section, 
as  described  below. 

Show  Alternate  Screen  (Release  3:  Alternate  Screen) 

Informs  you  that  you  are  looking  at  the  alternate  screen.  You  cannot 
select  this  mode  from  the  menu.  If  a check  mark  appears  beside  this 
mode,  you  are  viewing  the  alternate  screen.  Off  by  default. 

VT  Options  Menu  Commands 

These  commands  can  only  be  invoked  from  the  menu;  there  are  no  alternative  ways  to  perform 

the  same  functions. 

Do  Soft  Reset  (Release  3;  Soft  Reset) 

Resets  the  terminal  scroll  region  from  partial  scroll  (a  portion  of  the 
window)  to  full  scroll  (the  entire  window).  Use  this  command  when  a 
program  has  left  the  scroll  region  set  incorrectly. 

Do  Full  Reset  (Release  3:  Full  Reset) 

Clears  the  window,  resets  tabs  to  every  eight  columns,  and  resets  the 
terminal  modes  such  as  auto  wraparound  and  jump  scroll  to  their  ini- 
tial states. 

Show  Tek  Window  (Release  3:  Tek  Window  Showing) 

Shows  the  current  contents  of  the  Tektronix  window;  you  cannot  input 
to  that  window  until  you  choose  Switch  to  Tek  Mode.  Off  by  default. 
The  Release  3 item  appeared  in  the  mode  toggles  section  of  the  menu; 
the  item  has  been  renamed  and  moved  to  the  commands  section  in 
Release  4. 

Switch  to  Tek  Mode  (Release  3:  Select  Tek  Mode) 

Brings  up  a Tektronix  window.  You  can  input  to  this  window. 

Hide  VT  Window  Removes  the  VT  window  but  does  not  destroy  it.  It  can  be  brought 

back  by  choosing  Select  VT  Mode  from  the  Tek  Options  menu. 

Tek  Options  Menu  (Release  3:  Tektronix  Menu) 

The  Tek  Options  menu  (formerly  Tektronix)  sets  various  modes  in  the  Tektronix  emulation,  and 

is  displayed  when  the  Control  key  and  pointer  button  two  are  pressed  in  the  Tektronix  window. 

The  current  font  size  is  checked  in  the  modes  section  of  the  menu.  The  PAGE  entry  in  the  com- 
mand section  clears  the  Tektronix  window. 
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Tek  Options  Menu  Mode  Toggles  (On/Off) 

These  modes  can  only  be  set  from  the  Tek  Options  menu. 

Large  Characters  Selecting  one  of  these  four  options  sets  the  point  size  of  text 

#2  Size  Characters  displayed  in  the  Tektronix  window.  The  four  options  are 

#3  Size  Characters  mutually  exclusive. 

Small  Characters 


VT  Window  Showing  Shows  the  current  contents  of  the  VT102  window;  you  cannot  input 

to  that  window  until  you  choose  Switch  to  VT  Mode.  This  item  is  a 
mode  toggle  on  the  equivalent  Release  3 menu  (Tektronix).  In 
Release  4,  it  has  been  renamed  and  moved  to  the  commands  section, 
as  described  below. 


Tek  Options  Menu  Commands 

PAGE  Clears  the  Tektronix  window. 

RESET  Closes  down  the  Tektronix  window. 

COPY  Writes  a file  of  the  Tektronix  text  and  graphics  commands. 

Show  VT  Window  (Release  3:  VT  Window  Showing) 

Shows  the  current  contents  of  the  VT102  window;  you  cannot  input 
to  that  window  until  you  choose  Switch  to  VT  Mode.  The  Release  3 
item  appeared  in  the  mode  toggles  section  of  the  menu;  the  item  has 
been  renamed  and  moved  to  the  commands  section  in  Release  4. 

Switch  to  VT  Mode  (Release  3:  Select  VT  Mode) 

Makes  the  associated  VT102  window  active  for  input. 

Hide  Tek  Window  Removes  the  Tektronix  window  but  does  not  destroy  it.  It  can  be 

brought  back  by  choosing  Switch  to  Tek  Mode  from  the  VT  Options 
Menu  menu. 


VT  Fonts  Menu  (Release  4) 

Added  in  Release  4,  the  VT  Fonts  menu  enables  you  to  change  the  VT102  display  font  dynami- 
cally. The  menu  is  displayed  when  the  Control  key  and  pointer  button  three  are  pressed  in  the 
VT102  window.  All  items  on  the  menu  toggle  different  display  fonts.  The  items  are  mutually 
exclusive.  A checkmark  appears  on  the  menu  next  to  the  current  font. 

Default  Selecting  one  of  these  five  options  sets  the  point  size  of  text 

Tiny  displayed  in  the  VT102  window.  The  Default  font 

Small  is  the  font  specified  when  the  xterm  was  run. 

Medium 

Large 

Escape  Sequence  Allows  you  to  select  a font  previously  toggled  using  an  escape 

sequence.  See  Chapter  5,  Font  Specification,  for  the  escape 
sequence  to  use. 


X Window  System  User's  Guide 


501 


Reference  Pages 


xterm 


(continued) 


Window  Terminal  Emulator 


Selection  Allows  you  to  toggle  a font  whose  name  you’ve  previously  selected 

with  the  pointer  or  using  the  select  button  of  the  xfontsel  client.  See 
Chapter  5,  Font  Specification , for  more  information. 


Security 

X environments  differ  in  their  security  consciousness.  MIT  servers,  run  under  xdm , are  capable 
of  using  a “magic  cookie”  authorization  scheme  that  can  provide  a reasonable  level  of  security 
for  many  people.  If  your  server  is  only  using  a host-based  mechanism  to  control  access  to  the 
server  (see  xhost ),  then  if  you  enable  access  for  a host  and  other  users  are  also  permitted  to  run 
clients  on  that  same  host,  there  is  every  possibility  that  someone  can  run  an  application  that 
will  use  the  basic  services  of  the  X protocol  to  snoop  on  your  activities,  potentially  capturing  a 
transcript  of  everything  you  type  at  the  keyboard.  This  is  of  particular  concern  when  you  want 
to  type  in  a password  or  other  sensitive  data.  The  best  solution  to  this  problem  is  to  use  a better 
authorization  mechanism  that  host-based  control,  but  a simple  mechanism  exists  for  protecting 
keyboard  input  in  xterm. 

The  Main  Options  menu  (see  “Menus”  above)  contains  a Secure  Keyboard  entry  which,  when 
enabled,  ensures  that  all  keyboard  input  is  directed  only  to  xterm  (using  the  GrabKeyboard 
protocol  request).  When  an  application  prompts  you  for  a password  (or  other  sensitive  data), 
you  can  enable  Secure  Keyboard  using  the  menu,  type  in  the  data,  and  then  disable  Secure  Key- 
board using  the  menu  again.  Only  one  X client  at  a time  can  secure  the  keyboard,  so  when  you 
attempt  to  enable  Secure  Keyboard  it  may  fail.  In  this  case,  the  bell  will  sound.  If  the  Secure 
Keyboard  succeeds,  the  foreground  and  background  colors  will  be  exchanged  (as  if  you 
selected  the  Enable  Reverse  Video  entry  in  the  VT  Options  menu);  they  will  be  exchanged  again 
when  you  exit  secure  mode.  If  the  colors  do  not  switch,  then  you  should  be  very  suspicious  that 
you  are  being  spoofed.  If  the  application  you  are  running  displays  a prompt  before  asking  for 
the  password,  it  is  safest  to  enter  secure  mode  before  the  prompt  gets  displayed,  and  to  make 
sure  that  the  prompt  gets  displayed  correctly  (in  the  new  colors),  to  minimize  the  probability  of 
spoofing.  You  can  also  bring  up  the  menu  again  and  make  sure  that  a check  mark  appears  next 
to  the  entry. 

Secure  Keyboard  mode  will  be  disabled  automatically  if  your  xterm  window  becomes  iconified 
(or  otherwise  unmapped),  or  if  you  start  up  a reparenting  window  manager  (that  places  a title 
bar  or  other  decoration  around  the  window)  while  in  Secure  Keyboard  mode.  (This  is  a feature 
of  the  X protocol  not  easily  overcome.)  When  this  happens,  the  foreground  and  background 
colors  will  be  switched  back  and  the  bell  will  sound  in  warning. 

Character  Classes 

Clicking  the  middle  mouse  button  twice  in  rapid  succession  will  cause  all  characters  of  the 
same  class  (e.g.,  letters,  white  space,  punctuation)  to  be  selected.  Since  different  people  have 
different  preferences  for  what  should  be  selected  (for  example,  should  filenames  be  selected  as 
a whole  or  only  the  separate  subnames),  the  default  mapping  can  be  overridden  through  the  use 
of  the  charClass  (class  CharClass)  resource. 
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This  resource  is  simply  a list  of  range : val  ue  pairs  where  the  range  is  either  a single  number 
or  low -high  in  the  range  of  0 to  127,  corresponding  to  the  ASCII  code  for  the  character  or  char- 
acters to  be  set.  The  value  is  arbitrary,  although  the  default  table  uses  the  character  number 
of  the  first  character  occurring  in  the  set 

The  default  table  is: 


static  int  charClass [ 128]  = { 


/* 

NUL 

SOH 

STX 

ETX 

EOT 

ENQ 

ACK 

BEL  */ 

32, 

1, 

1, 

1, 

1, 

1, 

1, 

1, 

/* 

BS 

HT 

NL 

VT 

NP 

CR 

SO 

SI  */ 

1, 

32, 

1, 

1, 

1, 

1, 

1, 

1, 

/* 

DLE 

DC1 

DC2 

DC3 

DC4 

NAK 

SYN 

ETB  */ 

1, 

1, 

1, 

1, 

lr 

1, 

1, 

1, 

/* 

CAN 

EM 

SUB 

ESC 

FS 

GS 

RS 

US  */ 

1, 

1, 

1, 

1, 

1, 

1, 

1, 

1, 

/* 

SP 

i 

# 

$ 

% 

& 

' */ 

32, 

33, 

34, 

35, 

36, 

37, 

38, 

39, 

/* 

( 

) 

★ 

+ 

r 

- 

. 

/ */ 

40, 

41, 

42, 

43, 

44, 

45, 

46, 

47, 

/* 

0 

1 

2 

3 

4 

5 

6 

7 */ 

CD 

vr 

CD 

vr 

00 

00 

vr 

48, 

CD 

vr 

00 

vr 

00 

/* 

8 

9 

: 

; 

< 

= 

> 

? */ 

CO 

48, 

CO 

LO 

59, 

60, 

61, 

62, 

63, 

/* 

0 

A 

B 

C 

D 

E 

F 

G */ 

64, 

CD 

vr 

CD 

vr 

00 

00 

vr 

48, 

CO 

vr 

00 

vr 

/* 

H 

i 

j 

K 

L 

M 

N 

o */ 

CD 

vr 

CO 

vr 

48, 

48, 

00 

vr 

00 

48, 

48, 

/* 

p 

Q 

R 

S 

T 

u 

V 

W */ 

CD 

vr 

48, 

48, 

CO 

vr 

JS 

00 

48, 

48, 

00 

/* 

X 

Y 

Z 

[ 

\ 

] 

- 

*/ 

CO 

vr 

48, 

CO 

91, 

92, 

93, 

94, 

48, 

/* 

\ 

a 

b 

c 

d 

e 

f 

g */ 

96, 

00 

48, 

00 

vr 

00 

00 

vr 

CD 

•vr 

48, 

/* 

h 

i 

j 

k 

1 

m 

n 

o */ 

48, 

00 

•vr 

48, 

00 

00 

vr 

48, 

00 

vr 

00 

vr 

/* 

P 

q 

r 

s 

t 

u 

V 

w */ 

48, 

48, 

00 

00 

vr 

48, 

00 

00 

vr 

48, 

/* 

X 

y 

z 

{ 

1 

} 

DEL  */ 

CD 

VT 

48, 

00 

123, 

124, 

125, 

126, 

l}; 

For  example,  the  string  “33:48,37:48,45-47:48,64:48”  indicates  that  the  exclamation  mark, 
percent  sign,  dash,  period,  slash,  and  ampersand  characters  should  be  treated  the  same  way  as 
characters  and  numbers.  This  is  very  useful  for  cutting  and  pasting  electronic  mailing 
addresses  and  UNIX  filenames. 

Actions  (Release  4) 

It  is  possible  to  rebind  keys  (or  sequences  of  keys)  to  arbitrary  strings  for  input,  by  changing  the 
translations  for  the  vtlOO  or  tek4014  widgets.  Changing  the  translations  for  events  other 
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than  key  and  button  events  is  not  expected,  and  will  cause  unpredictable  behavior.  In  Release 
4,  the  following  actions  are  provided  for  using  with  the  vtlOO  or  tek4014  translations 
resource: 

bell ( [percent] ) 

Rings  the  keyboard  bell  at  the  specified  percentage  above  or  below  the  base  volume, 
ignore ( ) 

Ignores  the  event  but  checks  for  special  pointer  position  escape  sequences, 
insert  ( ) 

A synonym  for  insert-seven-bit  ( ) . 
insert-seven-bit () 

Inserts  the  7-bit  USASCII  character  or  string  associated  with  the  keysym  that  was  pressed, 
insert-eight-bit () 

Inserts  the  8-bit  ISO  Latin-1  character  or  string  associated  with  the  keysym  that  was 
pressed. 

insert-selection (sourcename  [,  . . . ]) 

Inserts  the  string  found  in  the  selection  or  cut  buffer  indicated  by  sourcename.  Sources 
are  checked  in  the  order  given  (case  is  significant)  until  one  is  found.  Commonly-used 
selections  include:  PRIMARY,  SECONDARY,  and  CLIPBOARD.  Cut  buffers  are  typically 
named  CUT_BUFFERO  through  CUT_BUFFER7. 

keymap (name) 

Dynamically  defines  a new  translation  table  whose  resource  name  is  name  with  the  suffix 
Keymap  (case  is  significant).  The  keymap  name  None  restores  the  original  translation 
table. 

popup-menu ( menuname ) 

Displays  the  specified  popup  menu.  Valid  names  (case  is  significant)  include:  main- 
Menu,  vtMenu,  f ontMenu,  and  tekMenu. 

secure  ( ) 

Toggles  the  secure  keyboard  mode  described  in  the  Security  section,  and  is  invoked  from 
the  Secure  Keyboard  entry  in  mainMenu. 

select-start ( ) 

Begins  text  selection  at  the  current  pointer  location.  See  the  section  on  “Pointer  Usage” 
for  information  on  making  selections. 

select-extend ( ) 

Tracks  the  pointer  and  extends  the  selection.  It  should  only  be  bound  to  motion  events, 
select-end (destname  [,  . . . ]) 

Puts  the  currently  selected  text  into  all  of  the  selections  or  cutbuffers  specified  by  dest- 
name. 

select-cursor-start  () 

Similar  to  select-start,  except  that  it  begins  the  selection  at  the  current  text  cursor 
position. 
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select-cursor-end (destname  [,  . . . ]) 

Similar  to  select -end,  except  that  it  should  be  used  with  select-cursor-start. 

set-vt-font (d/l/2/3/4/e/s  [, normal  font  [,  boldfont] ] ) 

Sets  the  font  or  fonts  currently  being  used  in  the  VT102  window.  The  first  argument  is  a 
single  character  that  specifies  the  font  to  be  used:  d or  d indicates  the  default  font  (the  font 
initially  used  when  xterm  was  started);  1 through  4 indicate  the  fonts  specified  by  the 
fontl  through  font  4 resources;  e or  E indicates  the  normal  and  bold  fonts  that  may  be 
set  through  escape  codes  (or  specified  as  the  second  and  third  action  arguments,  respec- 
tively); and  i or  I indicates  the  font  selection  (as  made  by  programs  such  as  xfontsel)  indi- 
cated by  the  second  action  argument. 

start-extend ( ) 

Similar  to  select-start  except  that  the  selection  is  extended  to  the  current  pointer 
location. 

start-cursor-extend ( ) 

Similar  to  select -extend  except  that  the  selection  is  extended  to  the  current  text  cur- 
sor position. 

string {string) 

Inserts  the  specified  text  string  as  if  it  had  been  typed.  Quotation  is  necessary  if  the  string 
contains  whitespace  or  non-alphanumeric  characters.  If  the  string  argument  begins  with 
the  characters  “Ox”,  it  is  interpreted  as  a hex  character  constant. 

scroll-back (count  [, units]) 

Scrolls  the  text  window  backward  so  that  text  that  had  previously  scrolled  off  the  top  of  the 
screen  is  now  visible.  The  count  argument  indicates  the  number  of  units  (which  may 
be  page,  halfpage,  pixel,  or  line)  by  which  to  scroll. 

scroll-forw (count  [, units]) 

Scrolls  is  similar  to  scroll-back  except  that  it  scrolls  the  other  direction. 

allow-send-events {on/of f /toggle) 

Sets  or  toggles  the  allowSendEvents  resource  and  is  also  invoked  by  the 
allowsends  entry  in  mainMenu. 

set-logging ( on/of f /toggle) 

Toggles  the  logging  resource  and  is  also  invoked  by  the  logging  entry  in  the  main- 
Menu. 

redraw ( ) 

Redraws  the  window  and  is  also  invoked  by  the  redraw  entry  in  mainMenu. 
send-signal ( signame ) 

Sends  the  signal  named  by  signame  (which  may  also  be  a number)  to  the  xterm  subprocess 
(the  shell  or  program  specified  with  the  -e  command  line  option)  and  is  also  invoked  by 
the  suspend,  continue,  interrupt,  hangup,  terminate,  and  kill  entries  in 
mainMenu.  Allowable  signal  names  are  (case  is  not  significant):  suspend,  tstp  (if  sup- 
ported by  the  operating  system),  cont  (if  supported  by  the  operating  system),  int,  hup,  term, 
and  kill. 
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quit  () 

Sends  a SIGHUP  to  the  subprogram  and  exits.  It  is  also  invoked  by  the  quit  entry  in 
mainMenu. 

set -scrollbar (on/of f /toggle) 

Toggles  the  scrollbar  resource  and  is  also  invoked  by  the  scrollbar  entry  in  vt- 
Menu. 

set- jumpscroll {on/off /toggle) 

Toggles  the  jumpscroll  resource  and  is  also  invoked  by  the  jumpscroll  entry  in 
vtMenu. 

set -reverse -video (on/off /toggle) 

Toggles  the  reverseVideo  resource  and  is  also  invoked  by  the  reversevideo  entry 
in  vtMenu. 

set-autowrap {on/of f /toggle) 

Toggles  automatic  wrapping  of  long  lines  and  is  also  invoked  by  the  autowrap  entry  in 
vtMenu. 

set-reversewrap (on/off /toggle) 

Toggles  the  reverseWrap  resource  and  is  also  invoked  by  the  reversewrap  entry  in 
vtMenu. 

set-autolinefeed {on/of f /toggle) 

Toggles  automatic  insertion  of  linefeeds  and  is  also  invoked  by  the  autolinefeed  entry 
in  vtMenu. 

set-appcursor  ton/off /toggle) 

Toggles  the  application  cursor  key  mode  and  is  also  invoked  by  the  appcursor  entry  in 
vtMenu. 

set-appkeypad ( on/of f /toggle) 

Toggles  the  application  keypad  mode  and  is  also  invoked  by  the  appkeypad  entry  in  vt- 
Menu. 

set -scroll-on-key ( on/off /toggle) 

Toggles  the  scrollKey  resource  and  is  also  invoked  from  the  scrollkey  entry  in  vt- 
Menu. 

set -sc roll -on- tty-output ( on/of f /toggle) 

Toggles  the  scrollTtyOutput  resource  and  is  also  invoked  from  the  scrollt- 
tyoutput  entry  in  vtMenu. 

set-allowl32 (on/of f /toggle) 

Toggles  the  cl 32  resource  and  is  also  invoked  from  the  allowl 32  entry  in  vtMenu. 
set-cursesemul {on/of f /toggle) 

Toggles  the  curses  resource  and  is  also  invoked  from  the  cursesemul  entry  in  vt- 
Menu. 
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set-visual-bell (on/of f /toggle) 

Toggles  the  visualBell  resource  and  is  also  invoked  by  the  visualbell  entry  in 
vtMenu. 

set-marginbell (on/of f /toggle) 

Toggles  the  marginBell  resource  and  is  also  invoked  from  the  marginbell  entry  in 
vtMenu. 

set-altscreen {on/off /toggle) 

Toggles  between  the  alternative  and  current  screens. 

soft-reset ( ) 

Resets  the  scrolling  region  and  is  also  invoked  from  the  soft  reset  entry  in  vtMenu. 
hard-reset ( ) 

Resets  the  scrolling  region,  tabs,  window  size,  and  cursor  keys  and  clears  the  screen.  It  is 
also  invoked  from  the  hardreset  entry  in  vtMenu. 

set-terminal-type (type) 

Directs  output  to  either  the  vt  or  tek  windows,  according  to  the  type  string.  It  is  also 
invoked  by  the  tekmode  entry  in  vtMenu  and  the  vtmode  entry  in  tekMenu. 

set-visibility (vt/tek,  on/of f /toggle) 

Controls  whether  or  not  the  vt  or  tek  windows  are  visible.  It  is  also  invoked  from  the 
tekshow  and  vthide  entries  in  vtMenu  and  the  vtshow  and  tekhide  entries  in 
tekMenu. 

set-tek-text (large/2 /3/small) 

Sets  font  used  in  the  Tektronix  window  to  the  value  of  the  resources  tektext large, 
tektext2,  tektext3,  and  tektextsmall  according  to  the  argument.  It  is  also  by 
the  entries  of  the  same  names  as  the  resources  in  tekMenu. 

tek-page ( ) 

Clears  the  Tektronix  window  and  is  also  invoked  by  the  tekpage  entry  in  tekMenu. 
tek-reset ( ) 

Resets  the  Tektronix  window  and  is  also  invoked  by  the  tekreset  entry  in  tekMenu. 
tek-copy ( ) 

Copies  the  escape  codes  used  to  generate  the  current  window  contents  to  a file  in  the  cur- 
rent directory  beginning  with  the  name  COPY.  It  is  also  invoked  from  the  tekcopy  entry 
in  tekMenu. 

The  Tektronix  window  also  has  the  following  action: 

gin-press  (1/L/m/M/r/R) 

Sends  the  indicated  graphics  input  code. 

The  default  bindings  in  the  VT102  window  are: 
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Shift 

<KeyPress> 

Prior : 

scroll-back (1, halfpage) \n\ 

Shift 

<KeyPress> 

Next : 

scroll-forw (1, halfpage) \n\ 

Shift 

<KeyPress> 

Select : 

select-cursor-start  ( ) \ 

select-cursor-end  (primary,  CUT  BUFFERO)  \n\ 

Shift 

<KeyPress> 

Insert : 

insert-selection  (PRIMARY,  CUT  BUFFERO)  \n\ 

'Meta 

<KeyPress> : 

insert-seven-bit () \n\ 

Meta 

<KeyPress> : 

insert-eight-bit () \n\ 

Ctrl 

'Meta 

<BtnlDown> : 

popup-menu (mainMenu) \n\ 

'Meta 

<BtnlDown> : 

select-start ( ) \n\ 

'Meta 

<BtnlMotion> : 

select-extend ( ) \n\ 

Ctrl 

'Meta 

<Btn2Down> : 

popup-menu (vtMenu) \n\ 

'Ctrl 

'Meta 

<Btn2Down> : 

ignore ( ) \n\ 

'Ctrl 

'Meta 

<Btn2Up> : 

insert-selection  (PRIMARY,  cut  BUFFERO)  \n\ 

Ctrl 

'Meta 

<Btn3Down> : 

popup-menu (fontMenu) \n\ 

'Ctrl 

'Meta 

<Btn3Down> : 

start-extend ( ) \n\ 

'Meta 

<Btn3Motion> : 

select-extend ( ) \n\ 

'Ctrl 

'Meta 

<BtnDown> : 

<BtnUp> : 
bell (0) 

The  default  bindings  in  the  Tektronix  window  are: 


'Meta 

<KeyPress> : 

insert-seven-bit  ( ) \n\ 

Meta 

<KeyPress> : 

insert-eight-bit ( ) \n\ 

Ctrl 

"Meta 

<BtnlDown> : 

popup-menu (mainMenu) \n\ 

Ctrl 

'Meta 

<Btn2Down> : 

popup-menu (tekMenu) \n\ 

Shift 

'Meta 

<BtnlDown> : 

gin-press (L) \n\ 

'Meta 

<BtnlDown> : 

gin-press (1) \n\ 

Shift 

'Meta 

<Btn2Down> : 

gin-press (M) \n\ 

'Meta 

<Btn2Down> : 

gin-press (m) \n\ 

Shift 

'Meta 

<Btn3Down> : 

gin-press (R) \n\ 

'Meta 

<Btn3Down> : 

gin-press (r) 

Below  is 

a sample  how  of  the  keymap  ( ) action  is  used  to  add  special 

monly-typed  works: 

*VT100 . 

Translations:  #override  <Key>F13:  keymap (dbx) 

*VT100 . 

dbxKeymap .translation 

s : \ 

<Key> 

F14  : 

keymap (None ) \n\ 

<Key> 

F17: 

string ( "next" ) 

string (OxOd) \n\ 

<Key> 

F18 : 

string ("step") 

string (OxOd) \n\ 

<Key> 

F19 : 

string ("continue")  string (OxOd) \n\ 

<Key> 

F20 : 

string ( "print 

")  insert-selection (PRIMARY 

Actions  (Release  3) 

It  is  possible  to  rebind  keys  (or  sequences  of  keys)  to  arbitrary  strings  for  input,  by  changing  the 
translations  for  the  vtlOO  or  tek4  014  widgets.  Changing  the  translations  for  events  other 
than  key  and  button  events  is  not  expected,  and  will  cause  unpredictable  behavior. 
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The  actions  available  for  key  translations  are: 

insert  ( ) Processes  the  key  in  the  normal  way;  i.e.,  inserts  the  ASCII  character  code 
corresponding  to  the  keysym  found  in  the  keyboard  mapping  table  into  the 
input  stream. 

string (string) 

Rebinds  the  key  or  key  sequence  to  the  string  value;  that  is,  inserts  the  string 
argument  into  the  input  stream.  Quotation  is  necessary  if  the  string  contains 
whitespace  or  non-alphanumeric  characters.  If  the  string  argument  begins 
with  the  characters  “Ox”,  it  is  interpreted  as  a hex  character  constant  and  the 
corresponding  character  is  sent  in  the  normal  way. 


keymap (name) 


Takes  a single  string  argument  naming  a resource  to  be  used  to  dynamically 
define  a new  translation  table;  the  name  of  the  resource  is  obtained  by 
appending  the  string  Keymap  to  name.  The  keymap  name  None  restores 
the  original  translation  table  (the  very  first  one;  a stack  is  not  maintained). 
Upper/lower  case  is  significant. 

insert-selection  (name[,name] . . . ) 

Retrieves  the  value  of  the  first  (leftmost)  named  selection  that  exists  or  cut 
buffer  that  is  non-empty  and  inserts  the  value  into  the  input  stream,  name  is 
the  name  of  any  selection,  for  example,  PRIMARY  or  SECONDARY,  or  the 
name  of  a cut  buffer:  CUT_BUFFERO,  . . . , CUT_BUFFER7.  Upper/lower  case 
is  significant. 

For  example,  a debugging  session  might  benefit  from  the  following  bindings: 


*VT100 . Translations : #override  <Key>F13:  keymap (dbx) 
*VT100 . dbxKeymap .translations : \ 

<Key>F14 : keymap (None)  \n\ 

<Key>F17:  string ( "next " ) string(OxOd)  \n\ 

<Key>F18:  string ( "step" ) string (OxOd)  \n\ 

<Key>F19:  string  ( "continue" ) string  (OxOd)  \n\ 
<Key>F20:  string ("print")  insert-selection (PRIMARY, 


CUT  BUFFERO) 


Within  the  VT100  widget  the  key  and  button  bindings  for  selecting  text,  pasting  text,  and 
activating  the  menus  are  controlled  by  the  translation  bindings.  In  addition  to  the  actions  listed 
above  under  Key  Translations,  the  following  actions  are  available: 


mode -menu  ( ) Posts  one  of  the  two  mode  menus,  depending  on  which  button  is  pressed. 


select-start ( ) 

Unselects  any  previously  selected  text  and  begins  selecting  new  text, 
select-extend ( ) 

Continues  selecting  text  from  the  previous  starting  position, 
start-extend ( ) 

Begins  extending  the  selection  from  the  farthest  (left  or  right)  edge. 
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select-end  (name[,name] . . . ) 

Ends  the  text  selection,  name  is  the  name  of  a selection,  or  the  name  of  a cut 
buffer  into  which  the  text  is  to  be  copied,  xterm  will  assert  ownership  of  all 
the  selections  named  and  will  copy  the  text  into  each  of  the  cut  buffers. 
Upper/lower  case  is  significant. 

ignore  ( ) Quietly  discards  the  key  or  button  event. 

bell([  volume]) 

Rings  the  bell  at  the  specified  vol  ume  increment  above/below  the  base  vol- 
ume. 

The  default  bindings  are: 


<KeyPress> : 

insert ( ) \n\ 

Ctrl 

'Meta 

<BtnlDown> : 

mode-menu ( ) \n\ 

'Meta 

<BtnlDown> : 

select-start ( ) \n\ 

'Meta 

<BtnlMotion> : 

select-extend ( ) \n\ 

Ctrl 

'Meta 

<Btn2Down> : 

mode-menu ( ) \n\ 

'Ctrl 

'Meta 

<Btn2Down> : 

ignore ( ) \n\ 

'Meta 

<Btn2Up> : 

insert-selection  (PRIMARY,  CUT_BUFFERO)  \n\ 

'Ctrl 

'Meta 

<Btn3Down> : 

start-extend ( ) \n\ 

'Meta 

<Btn3Motion> : 

select-extend ( ) \n\ 

'Meta 

<BtnUp> : 
<BtnDown> : 

select-end  (PRIMARY,  CUT_BUFFER0 ) \n\ 
bell (0) 

An  Obsolete  Feature:  Starting  xterm  from  Init 

Warning:  This  feature  is  now  obsolete.  It  is  not  supported  in  Release  4.  If  Release  3 is  run- 
ning at  your  site,  this  method  may  still  be  in  use.  However,  sites  using  this  method  should 
switch  to  xdm  instead. 

On  operating  systems  such  as  BSD  4.3  and  Ultrix,  the  server  and  initial  login  window  are  nor- 
mally started  automatically  by  init( 8). 

By  convention,  the  pseudo-terminal  with  the  highest  minor  device  number  (e.g.,  devttyqf  and 
devptyqf)  is  renamed  for  the  lowest  display  number  (e.g.,  devttyvO  and  devptyvO).  Machines 
that  have  more  than  one  display  can  repeat  this  process  using  ttyqe  for  ttyvl , and  so  on. 

Once  the  pseudo-terminals  are  in  place,  a line  similar  to  the  following  may  be  added  to  /etc/ttys 
(replacing  Xqvss  with  the  appropriate  server  and  putting  it  all  on  one  line): 

ttyvO  "/usr/bin/Xll/xterm  -L  -geom  80x24+1+1  -display  :0" 
xterm  on  secure  window="/usr/bin/Xll/Xqvss  :0" 

Sites  that  used  to  run  X10  should  note  that  the  colon  in  the  server  display  number  is  required. 

Although  the  release  will  install  both  the  X server  and  xterm  in  /usr/bin/Xll  by  default,  many 
sites  choose  to  make  a copy  of  both  of  these  programs  on  the  root  partition  (usually  in  /etc)  so 
that  they  may  still  be  used  even  if  the  partition  containing  lusrlbin/Xll  isn’t  mounted. 
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Some  versions  of  init  have  relatively  small  program  name  buffer  sizes  and  treat  all  sharp  signs 
as  comment  delimiters.  Sites  that  wish  to  list  large  numbers  of  options  on  the  xterm  line  will 
need  to  write  a small  shell  script  to  execute  the  long  xterm  line.  The  best  solution,  of  course,  is 
to  use  xdm. 

Other  Features 

xterm  automatically  highlights  the  window  border  and  text  cursor  when  the  pointer  enters  the 
window  (selected)  and  unhighlights  them  when  the  pointer  leaves  the  window  (unselected).  If 
the  window  is  the  focus  window,  then  the  window  is  highlighted  no  matter  where  the  pointer  is. 

In  VT102  mode,  there  are  escape  sequences  to  activate  and  deactivate  an  alternate  screen  buf- 
fer, which  is  the  same  size  as  the  display  area  of  the  window.  When  activated,  the  current 
screen  is  saved  and  replaced  with  the  alternate  screen.  Saving  of  lines  scrolled  off  the  top  of 
the  window  is  disabled  until  the  normal  screen  is  restored.  The  termcap  entry  for  xterm  allows 
the  visual  editor  vi  to  switch  to  the  alternate  screen  for  editing,  and  restore  the  screen  on  exit. 

In  either  VT102  or  Tektronix  mode,  there  are  escape  sequences  to  change  the  name  of  the  win- 
dows and  to  specify  a new  log  file  name. 

Environment 

xterm  sets  the  environment  variables  TERM  and  TERMCAP  properly  for  the  size  window  you 
have  created.  It  also  uses  and  sets  the  environment  variable  DISPLAY  to  specify  which  bitmap 
display  terminal  to  use.  The  environment  variable  WINDOWID  is  set  to  the  X window  ID  num- 
ber of  the  xterm  window. 

Bugs 

The  class  name  is  XTerm  instead  of  xterm. 

The  -L  option  is  no  longer  needed  since  the  display  manager,  xdm,  handles  logging  in  much 
more  cleanly.  No  more  trying  to  match  colors  in  letc/ttys  or  worrying  about  an  unwanted  login 
window.  (The  -L  option  has  been  removed  in  Release  4.) 

x term  will  hang  forever  if  you  try  to  paste  too  much  text  at  one  time.  It  is  both  producer  and 
consumer  for  the  pty  and  can  deadlock. 

Variable-width  fonts  are  not  handled  reasonably. 

This  program  still  needs  to  be  rewritten.  It  should  be  split  into  very  modular  sections,  with  the 
various  emulators  being  completely  separate  widgets  that  don’t  know  about  each  other.  Ideally, 
you’d  like  to  be  able  to  pick  and  choose  emulator  widgets  and  stick  them  into  a single  control 
widget. 

The  focus  is  considered  lost  if  some  other  client  (e.g.,  the  window  manager)  grabs  the  pointer; 
it  is  difficult  to  do  better  without  an  addition  to  the  protocol. 

There  needs  to  be  a dialog  box  to  allow  entry  of  the  log  file  name  and  the  COPY  filename. 

Many  of  the  options  are  not  resettable  after  xterm  starts. 

The  Tek  widget  does  not  support  key/button  re-binding. 
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See  Also 

X,  resize,  pty(4),  tty(4);  Appendix  E,  xterm  Control  Sequences 

Authors 

Far  too  many  people,  including: 

Loretta  Guarino  Reid  (DEC-UEG-WSL),  Joel  McCormack  (DEC-UEG-WSL),  Terry  Weissman 
(DEC-UEG-WSL),  Edward  Moy  (Berkeley),  Ralph  R.  Swick  (MIT-Athena),  Marie  Vande- 
voorde  (MIT-Athena),  Bob  McNamara  (DEC-MAD),  Jim  Gettys  (MIT-Athena),  Bob  Scheifler 
(MIT  X Consortium),  Doug  Mink  (SAO),  Steve  Pitschke  (Stellar),  Ron  Newman  (MIT- 
Athena),  Jim  Fulton  (MIT  X Consortium),  Dave  Serisky  (HP). 
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Name 

xwd  - place  window  images  in  a dump  file. 


Syntax 

xwd [ options ] 


Description 

xwd  stores  window  images  in  a specially  formatted  window  dump  file.  This  file  can  then  be 
read  by  various  other  X utilities  for  redisplay,  printing,  editing,  formatting,  archiving,  image 
processing,  etc.  The  target  window  is  selected  by  clicking  the  mouse  in  the  desired  window. 
The  keyboard  bell  is  rung  once  at  the  beginning  of  the  dump  and  twice  when  the  dump  is  com- 
pleted. 


Options 

-help  Prints  out  the  ’Usage:’  command  syntax  summary. 


-nobdrs  Specifies  that  the  window  dump  should  not  include  the  pixels  that  compose 
the  X window  border.  This  is  useful  when  the  window  contents  are  included 
in  a document  as  an  illustration. 


-out  file 


-xy 


-root 


Allows  you  to  specify  the  output  file  on  the  command  line.  The  default  out- 
puts to  the  standard  output  ( stdout ). 

Applies  to  color  displays  only.  The  -xy  option  selects  ‘XY’  pixmap  format 
dumping  instead  of  the  default  ‘Z’  pixmap  format. 

Makes  a dump  of  the  entire  root  window. 


-add  val  ue  Specifies  a signed  value  to  be  added  to  every  pixel. 


-frame  Indicates  that  the  window  manager  frame  should  be  included  when  manually 

selecting  a window.  (Available  as  of  Release  4.) 


-display  [host] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  is  the 
machine,  server  is  the  server  number  and  screen  is  the  screen  number. 
For  example. 


xwd  -display  your_node: 0.1  & 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 


Files 

XWDFile.h  X Window  Dump  File  format  definition  file. 

See  Also 

X,  xdpr,  xpr,  xwud 


X Window  System  User's  Guide 


513 


Reference  Pages 


xwd 


(continued) 


Window  Image  Dumper 


Author 

Tony  Della  Fera,  Digital  Equipment  Corp.,  MIT  Project  Athena; 
William  F.  Wyatt,  Smithsonian  Astrophysical  Observatory. 


514 


X Window  System  User’s  Guide 


—Window  Information  Utility 


xwininfo 


/ 


Name 

xwininfo  - window  information  utility  for  X. 

Syntax 

xwininfo  [options] 

Description 

xwininfo  is  a utility  for  displaying  information  about  windows.  Depending  on  which  options 
are  choosen,  various  information  is  displayed.  If  no  options  are  choosen,  -stats  is  assumed. 

The  user  has  the  option  of  selecting  the  target  window  with  the  mouse  (by  clicking  any  mouse 
button  in  the  desired  window)  or  by  specifying  its  window  id  on  the  command  line  with  the 
-id  option.  Or  instead  of  specifying  the  window  by  its  id  number,  the  -name  option  may  be 
used  to  specify  the  window  by  name.  There  is  also  a special  -root  option  to  quickly  obtain 
information  on  the  root  window. 

Options 

-display  [host]  : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xwininfo  -display  your_node: 0.1  & 

specifies  screen  1 of  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  screen  0 is 
assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 

Prints  out  the  ’Usage;’  command  syntax  summary. 

Allows  the  user  to  specify  a target  window  id  on  the  command  line  rather 
than  using  the  mouse  to  select  the  target  window.  This  is  very  useful  in 
debugging  X applications  where  the  target  window  is  not  mapped  to  the 
screen  or  where  the  use  of  the  mouse  might  be  impossible  or  interfere  with 
the  application. 

Allows  the  user  to  specify  that  the  window  named  name  is  the  target  window 
on  the  command  line  rather  than  using  the  mouse  to  select  the  target  window. 

Specifies  that  the  root  window  is  the  target  window.  This  is  useful  in  situa- 
tions where  the  root  window  is  completely  obscured. 

Causes  window  manager  frames  not  to  be  ignored  when  manually  selecting 
windows.  (Available  as  of  Release  4.) 

Specifies  that  all  X window  ids  should  be  displayed  as  integer  values.  The 
default  is  to  display  them  as  hexadecimal  values. 

Causes  the  root,  parent,  and  children  windows’  ids  and  names  of  the  selected 
window  to  be  displayed. 


-help 
-id  id 

-name  name 

-root 

-frame 

-int 

-tree 
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-stats 

Causes  various  attributes  of  the  selected  window  having  to  do  with  its  loca- 
tion and  appearence  to  be  displayed.  Information  displayed  includes  the 
location  of  the  window,  its  width,  height,  depth,  border  width,  class,  and  map 
state,  colormap  ID  (if  any),  backing-store  hint,  and  the  location  of  its  comers. 
If  xwininfo  is  run  with  no  options,  -stats  is  assumed. 

-bits 

Causes  the  display  of  various  attributes  pertaining  to  the  selected  window’s 
raw  bits  and  how  the  selected  window  is  to  be  stored  to  be  displayed.  Infor- 
mation displayed  includes  the  selected  window’s  bit  gravity,  window  gravity, 
backing  store  hint,  backing  planes  value,  backing  pixel,  and  whether  or  not 
the  window  has  save-under  set 

-events 

Causes  the  selected  window’s  event  masks  to  be  displayed.  Both  the  event 
mask  of  events  wanted  by  some  client  and  the  event  mask  of  events  not  to 
propagate  are  displayed. 

-size 

Causes  the  selected  window’s  sizing  hints  to  be  displayed.  Information 
displayed  includes:  for  both  the  normal  size  hints  and  the  zoom  size  hints  the 
user  supplied  location  if  any;  the  program  supplied  location  if  any;  the  user 
supplied  size  if  any;  the  program  supplied  size  if  any;  the  minimum  size  if 
any;  the  maximum  size  if  any;  the  resize  increments  if  any;  and  the  minimum 
and  maximum  aspect  ratios  if  any. 

-wra 

Causes  the  selected  window’s  window  manager  hints  to  be  displayed.  Infor- 
mation displayed  may  include  whether  or  not  the  application  accepts  input, 
what  the  window’s  icon  window  # and  name  is,  where  the  window’s  icon 
should  go,  and  what  the  window’s  initial  state  should  be. 

-metric 

Causes  all  individual  height,  width,  and  x and  y positions  to  be  displayed  in 
millimeters,  as  well  as  number  of  pixels,  based  on  what  the  server  thinks  the 
resolution  is.  Geometry  specifications  that  are  in  +x+y  form  are  not  changed. 

-english 

Causes  all  individual  height,  width,  and  x and  y positions  to  be  displayed  in 
inches  (and  feet,  yards,  and  miles  if  necessary),  as  well  as  number  of  pixels, 
-metric  and  -english  may  be  used  at  the  same  time. 

-all 

A quick  way  to  ask  for  all  information  possible. 

Examples 

The  following  is  a sample  summary  taken  with  no  options  specified. 

xwininfo  ==>  Please  select  the  window  you  wish 
==>  information  on  by  clicking  the 


xwininfo  = 

==>  mouse  in  that  window. 

==>  Window  id:  0x30000f  (xterm) 

==>  Upper  left  X:  0 

==>  Upper  left  Y:  0 
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==>  Width:  578 

==>  Height:  316 

==>  Depth:  1 

==>  Border  width:  1 

==>  Window  class:  InputOutput 

==>  Colormap:  0x80065 

==>  Window  Bit  Gravity  State:  NorthWestGravity 

==>  Window  Window  Gravity  State:  NorthWestGravity 

==>  Window  Backing  Store  State:  NotUseful 

==>  Window  Save  Under  State:  no 

==>  Window  Map  State:  IsUnviewable 

==>  Window  Override  Redirect  State:  no 

==>  Corners:  +0+0  -572+0  -572-582  +0-582 


Bugs 

Using  -stats  and  -bits  together  shows  some  redundant  information. 


See  Also 

X,  xprop 


Author 

Mark  Lillibridge,  MIT  Project  Athena. 
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Name 

xwud  - X window  image  displayer. 

Syntax 

xwud  [options] 

Description 

xwud  is  an  X Window  System  window  image  undumping  utility,  xwud  allows  X users  to  dis- 
play a window  image  saved  in  a specially  formatted  dump  file,  such  as  one  produced  by  xwd. 

The  Release  4 version  of  xwud  allows  you  to  specify  the  coordinates  at  which  this  image  is 
displayed  using  the  -geometry  option.  If  you  are  using  the  Release  3 version  of  xwud,  the 
window  image  will  appear  at  the  coordinates  of  the  original  window  from  which  the  dump  was 
taken. 

Options 

-help  Prints  out  a short  description  of  the  allowable  options. 

-in  file  Allows  the  user  to  explicitly  specify  the  input  file  on  the  command  line.  The 
default  is  to  take  input  from  standard  input. 

-display  [host] : server[ . screen] 

Allows  you  to  specify  the  host,  server  and  screen  to  connect  to.  host  speci- 
fies the  machine,  server  specifies  the  server  number,  and  screen  specifies 
the  screen  number.  For  example, 

xwud  -display  your_node: 0 . 1 

specifies  screen  1 on  server  0 on  the  machine  your_node.  If  the  host  is 
omitted,  the  local  machine  is  assumed.  If  the  screen  is  omitted,  the  screen  0 
is  assumed;  the  server  and  colon  (:)  are  necessary  in  all  cases. 

-geometry  geometry 

The  xwud  window  is  created  with  the  specified  size  and  location  determined 
by  the  supplied  geometry  specification.  The  -geometry  option  can  be  (and 
often  is)  abbreviated  to  -g,  unless  there  is  a conflicting  option  that  begins 
with  “g.”  The  argument  to  the  geometry  option  ( geometry ) is  referred  to  as 
a “standard  geometry  string,”  and  has  the  form  widthx- 
height±xoff±yoff.  (This  option  is  available  for  use  with  xwud  as  of 
Release  4.) 

Typically,  you  will  only  want  to  specify  the  position  and  let  the  size  default  to 
the  actual  size  of  the  image. 

-bg  col  or  If  a bitmap  image  (or  a single  plane  of  an  image)  is  displayed,  this  option  can 
be  used  to  specify  the  color  to  display  for  the  “0”  bits  in  the  image.  (Avail- 
able as  of  Release  4.) 

-f  g color  If  a bitmap  image  (or  a single  plane  of  an  image)  is  displayed,  this  option  can 

be  used  to  specify  the  color  to  display  for  the  “1”  bits  in  the  image.  (Avail- 
able as  of  Release  4.) 
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(continued) 


xwud 


-new  Forces  creation  of  a new  colormap  for  displaying  the  image.  If  the  image 

characteristics  happen  to  match  those  of  the  display,  this  can  get  the  image  on 
the  screen  faster,  but  at  the  cost  of  using  a new  colormap  (which  on  most  dis- 
plays will  cause  other  windows  to  go  technicolor).  (Available  as  of  Release 
4.) 

-noclick  Clicking  any  button  in  the  window  will  terminate  the  application,  unless  this 
option  is  specified.  Termination  can  always  be  achieved  by  typing  ’q’,  ’Q’,  or 
Ctrl-c.  (Available  as  of  Release  4.) 


-plane  number 

Selects  a single  bit  plane  of  the  image  to  display.  Planes  are  numbered  with 
zero  being  the  least  significant  bit.  This  option  can  be  used  to  figure  out 
which  plane  to  pass  to  xpr  for  printing.  (Available  as  of  Release  4.) 


-raw 


-rv 


Forces  the  image  to  be  displayed  with  whatever  color  values  happen  to  cur- 
rently exist  on  the  screen.  This  option  is  mostly  useful  when  undumping  an 
image  back  onto  the  same  screen  that  the  image  originally  came  from,  while 
the  original  windows  are  still  on  the  screen,  and  results  in  getting  the  image 
on  the  screen  faster.  (Available  as  of  Release  4.) 


If  a bitmap  image  (or  a single  plane  of  an  image)  is  displayed,  this  option 
forces  the  foreground  and  background  colors  to  be  swapped.  This  may  be 
needed  when  displaying  a bitmap  image  which  has  the  color  sense  of  pixel 
values  “0”  and  “1”  reversed  from  what  they  are  on  your  display.  (Available 
as  of  Release  4.) 


-std  map_type 


Causes  the  image  to  be  displayed  using  the  specified  Standard  Colormap. 
The  property  name  is  obtained  by  converting  the  type  to  upper  case,  prepend- 
ing “RGB_”,  and  appending  “_MAP”.  Typical  types  are  best,  default, 
and  gray.  See  xstdcmap  for  one  way  of  creating  Standard  Colormaps. 
(Available  as  of  Release  4.) 


-vis  vis_type_or__ID 

Allows  you  to  specify  a particular  visual  or  visual  class.  The  default  is  to 
pick  the  “best”  one.  A particular  class  can  be  specified:  StaticGray, 
Grayscale,  StaticColor,  Pseudocolor,  DirectColor, or  True- 
Color.  Or  Match  can  be  specified,  meaning  use  the  same  class  as  the 
source  image.  Alternatively,  an  exact  visual  ID  (specific  to  the  server)  can  be 
specified,  either  as  a hexadecimal  number  (prefixed  with  “Ox”)  or  as  a deci- 
mal number.  Finally,  “default”  can  be  specified,  meaning  to  use  the  same 
class  as  the  colormap  of  the  root  window.  Case  is  not  significant  in  any  of 
these  strings.  (Available  as  of  Release  4.) 

-inverse  Applies  to  monochrome  window  dump  files  only.  If  selected,  the  window  is 
undumped  in  reverse  video.  This  is  mainly  needed  because  the  display  is 
‘write  white’,  whereas  dump  files  intended  eventually  to  be  written  to  a 
printer  are  generally  ‘write  black’.  (Available  in  Release  3 only.) 
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Files 

XWDFile.h  X Window  Dump  File  format  definition  file. 

Bugs  In  Release  3 

Does  not  attempt  to  do  color  translation  when  the  destination  screen  does  not  have  a colormap 
exactly  matching  that  of  the  original  window. 

See  Also 

X,  xdpr,  xpr,  xstdcmap,  xwd 

Author 

Release  4 version  by  Bob  Scheifler,  MIT  X Consortium; 

Release  3 version  by  Tony  Della  Fera,  Digital  Equipment  Corp.  and  MIT  Project  Athena,  and 
William  F.  Wyatt,  Smithsonian  Astrophysical  Observatory. 
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This  part  of  the  book  contains  useful  reference  information. 
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System  Management 

This  appendix  discusses  various  tasks  involved  in  X Window  System  man- 
agement, mostly  from  the  UNIX  point  of  view. 

In  This  Chapter: 

Including  X in  Your  Search  Path 526 

Setting  the  Terminal  Type  526 

A Startup  Shell  Script 527 

What  Should  Go  in  the  Script 527 

Starting  X 531 

Starting  X with  the  Display  Manager,  xdm  (Release  4)  531 

Getting  Started  with  xdm  on  a Single  Display 532 

Setting  Up  the  Configuration  File  and  Other  Special  Files 532 

The  Standard  Login  Session 535 
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The  Xsession  File  and  .xsession  Scripts  538 
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The  Error  Log  File 539 

The  xdm-pid  File  (Release  4 Only) 539 

Xstartup  and  Xreset 539 
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Release  3 xdm 541 
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X exists  in  so  many  incarnations  and  runs  on  so  many  different  versions  of  UNIX  (not  to  men- 
tion other  operating  systems)  that  it  is  difficult  to  be  definitive  about  system  management. 
This  appendix  discusses  several  topics  relevant  to  setting  up  the  standard  version  of  X (with 
UNIX)  and  keeping  it  running  smoothly.  The  range  of  subjects  discussed  is  somewhat  broad. 
Here’s  an  overview. 

This  appendix  primarily  focuses  on  ways  in  which  you  can  set  up  X to  run  automatically: 

• xdm,  the  display  manager. 

• xinit. 

• By  an  older  (and  now  obsolete)  method,  running  xterm  from  I etc!  ttys. 

In  addition  to  information  relating  to  starting  X,  we’ve  also  included  brief  discussions  of 
other  topics  relevant  to  X system  management: 

• Including  X in  your  search  path. 

• Setting  the  terminal  type  for  xterm. 

• Managing  fonts. 

• Addressing  security  issues  and  access  control. 

• Redirecting  console  messages. 

• Maintaining  log  files. 

• Changing  the  color  name  database. 

Given  the  various  incarnations  of  X and  UNIX,  you  should  be  sure  to  check  your  system’s 
documentation  for  additional  (or  contrary)  details. 
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Including  X in  Your  Search  Path 


The  various  X clients  are  normally  stored  in  the  directory  /usr/bin/Xll.  In  order  to  invoke 
them  by  name  like  any  other  UNIX  program,  you  need  to  make  this  directory  part  of  your 
search  path.* 

This  is  normally  done  from  your  .cshrc  (C  shell)  or  .profile  (Bourne  shell)  file,  using  a com- 
mand similar  to  the  following: 

Bourne  Shell: 

PATH=. : /usr/ucb : /bin : /usr/bin : /usr/bin/Xl 1 : Other  directories; 
export  PATH 

C Shell: 

set  path= ( . /usr/ucb  /bin  /usr/bin  /usr/bin/Xll  Other  directories) 

The  exact  list  of  directories  will  differ  from  system  to  system.  You  should  be  aware  that 
directories  are  searched  in  order  from  left  to  right,  so  a command  with  the  same  name  in  an 
earlier  directory  will  be  found  and  used  before  one  in  a later  directory.  Many  users  take 
advantage  of  this  fact  to  run  customized  versions  of  programs  by  putting  (the  current 
directory)  or  a local  tools  directory  first  in  their  search  path.  This  works  fine,  but  you  should 
be  aware  that  this  provides  a security  loophole  that  can  be  taken  advantage  of  by  an  experi- 
enced system  cracker.  It’s  much  safer  to  put  at  the  end  of  your  path,  or  eliminate  it 
entirely. 

If  you  have  already  logged  in  before  adding  the  above  line  to  your  .profile  or  .cshrc  file,  you 
should  log  out  and  log  in  again,  or  type  in  the  path-setting  command  at  your  prompt,  so  that  it 
takes  effect  for  your  current  session. 


Setting  the  Terminal  Type 

Several  termcap  entries  work  with  xterm,  including  “xterm,”  “vtl02,”  “vtlOO,”  and  “ansi.” 
The  xterm  program  automatically  searches  the  termcap  file  for  these  entries  (in  this  order) 
and  sets  the  TERM  and  TERMCAP  environment  variables  according  to  the  entry  it  finds. 

We’ve  found  that  the  termcap  entry  called  “xterm,”  which  comes  with  the  standard  X distri- 
bution, provides  very  reliable  emulation.  We  suggest  you  copy  this  entry  from  the  xterm 
source  directory  (the  file  is  called  termcap ) and  add  it  as  the  first  entry  in  the  /etc/termcap  file 
on  your  system.  This  will  allow  you  to  set  your  terminal  type  to  xterm. 


♦This  topic  isn’t  really  part  of  system  management,  but  since  we  assume  most  people  know  how  to  do  it,  we  didn’t 
want  to  clutter  up  Chapter  2 with  unnecessary  discussion.  On  the  other  hand,  the  information  is  critical  for  those  who 
don’t  already  know  it,  so  we  wanted  to  put  it  somewhere! 
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A Startup  Shell  Script 


It’s  a basic  principle  of  UNIX  to  “let  the  computer  do  the  work.”  Accordingly,  you’d  no 

doubt  like  to  run  various  X clients  automatically  whenever  you  log  in. 

The  best  way  to  do  this  is  to  create  a script  that  runs  the  clients  you  want.  Depending  on  how 

X is  set  up  on  your  system,  you  can  execute  this  script  in  one  of  two  ways:* 

• If  xdm  is  running  X,  name  the  script  x session  and  put  it  in  your  home  directory.  When 
you  log  in,  xdm  will  automatically  execute  your  x session  script. 

• If  you  are  starting  X with  j unit,  name  the  script  xinitrc  and  put  it  in  your  home  directory. 
Then  put  the  command  xinit  at  the  end  of  your  .login  file,  xinit  normally  starts  the  server 
and  runs  a single  xterm  as  a client,  but  if  a file  called  xinitrc  exists  in  your  home  direc- 
tory, xinit  starts  the  server  and  executes  xinitrc. 

Methods  of  starting  X automatically  with  xinit  or  xdm  are  discussed  later  in  this  appendix. 


What  Should  Go  in  the  Script 

With  some  variation  depending  on  the  specific  environment,  in  most  cases  your  startup  script 
should: 

• Set  the  DISPLAY  environment  variable. 

• Load  your  resources  file  with  xrdb. 

• Start  the  window  manager. 

• Start  other  clients  you  want  on  your  default  display,  such  as  xterm,  oclock,xload,  etc. 

• Run  a console  xterm  process  in  the  foreground;  terminating  this  process  will  terminate 
the  login  session. 

The  script  can  be  either  a C shell  or  Bourne  shell  script.  We’ve  included  a sample  script  in 
Bourne  shell  syntax.! 

In  writing  a script,  keep  in  mind  this  limitation:  running  xterm  from  inside  a shell  script  only 
works  if  the  script  executes  quickly — or  does  not  terminate  at  all. 

The  problem  involves  the  way  that  xterm  sets  up  its  controlling  terminal  (/dev/ tty).  If  the 
xterm' s parent  process  has  died  by  the  time  the  xterm  gets  around  to  doing  this,  then  /dev/ tty 
is  redefined  properly.  If  the  parent  has  not  died,  however,  xterm  uses  the  parent’s  controlling 
terminal  as  its  own.  If  the  parent  dies  at  any  time  after  that,  /dev/tty  will  become  undefined 
for  that  xterm  (and  all  processes  spawned  by  it). 


*If  you  are  still  starting  the  X server  from  the  letclttys  file,  as  described  later  in  this  appendix,  this  will  bring  up  an 
xterm  window  with  a login  prompt.  In  this  case,  you  can  run  the  script  to  start  other  clients  from  your  .login  file. 
Note,  however,  that  this  method  of  starting  the  X server  is  not  supported  in  Release  4. 
t Thanks  to  Dave  Curry  for  his  help  in  preparing  this  sample. 
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A C shell  script  that  starts  up  a few  xterms  and  then  exits  will  probably  work  because  the 
xterm's  parent  process  (the  script)  has  exited  by  the  time  the  xterms  start  defining  their 
Idevltty.  If,  however,  there  is  a sleep  or  another  command  that  takes  a long  time  in  the  script 
after  the  line  invoking  the  xterm,  the  parent  may  still  be  around  when  the  xterm  defines 
Idevltty.  Then,  when  the  script  finally  exits,  Idevltty  becomes  undefined  for  those  xterms. 

If  you  want  to  use  a C shell  script,  this  problem  can  be  avoided  by  enclosing  commands  in 
parentheses.  This  causes  the  shell  to  fork  an  extra  time  before  executing  the  command,  and 
thus  disassociates  the  process  from  the  controlling  terminal  before  the  process  begins. 

Whether  you  are  using  a C shell  or  Bourne  shell  script,  you  should  make  the  last  command  in 
the  script  be  one  that  opens  a window,  and  run  that  command  in  the  foreground.  Then  the 
script  will  not  terminate  until  that  final  foreground  command  terminates — that  is,  when  you 
kill  the  window.  In  this  case,  all  the  xterms  will  have  the  script’s  controlling  tty,  but  since  the 
script  is  guaranteed  to  hang  around,  this  causes  no  problem. 

Regardless  of  how  and  in  what  environment  you’re  starting  X,  it  is  advisable  to  set  the  DIS- 
PLAY variable  inside  the  script,  since  otherwise  the  clients  won’t  know  which  display  to  con- 
nect to.  (Normally,  xterm  sets  the  DISPLAY  variable.  Since  you  are  invoking  the  other  cli- 
ents not  from  a shell  in  an  xterm  window,  but  from  a standard  shell,  it  will  not  automatically 
be  set.) 

Though  without  explicit  settings,  both  xdm  and  xinit  will  automatically  set  DISPLAY  to 
unix : 0 . 0 (or  some  variation  thereof),  this  default  setting  limits  the  remote  hosts  that  can 
connect  to  the  local  system.  (If  every  system  has  the  same  DISPLAY  variable,  it  becomes 
rather  difficult  to  run  programs  on  a remote  host!)  We  suggest  you  set  the  DISPLAY  expli- 
citly, determining  the  appropriate  host  name  with  the  hostname  command,  as  shown  in  the 
script  below. 

Note  that  the  hostname  command  is  a BSD  command.  For  a System  V equivalent,  see  your 
UNIX  documentation.  Note  also  that  in  this  script,  sed  is  used  to  strip  domained-based  host- 
names  such  as  isla.ora.com  back  to  their  initial  term,  the  actual  system  name.  If  you  are  run- 
ning in  a standalone  environment,  this  is  not  necessary. 

Example  A-l  shows  a startup  Bourne  shell  script,  which  would  open  windows  on  the  display, 
as  shown  in  Figure  A-l.  You  can  use  this  script  even  if  you  normally  use  the  C shell  for 
interactive  use.  Note  that  the  comments  should  probably  not  be  present  in  the  working  script. 
While  they  are  ignored,  they  do  slow  down  execution,  and  on  a loaded  system  can  cause  X to 
start  up  improperly. 

Example  A-1.  Startup  Bourne  shell  script 

# ! /bin/ sh 

# Get  hostname,  strip  the  domain  name  if  there  is  one 
cpu= 'hostname  | sed  -e  rs/\..*//,x 

# If  no  DISPLAY  is  set,  set  one. 

if  [ -z  SDISPLAY  ] 
then 

DI SPLAY=$cpu : 0 
fi 


528 


X Window  System  User's  Guide 


Example  A-1.  Startup  Bourne  shell  script  (continued) 

# Special-case  the  "bogus"  non-network  display  names  and 

# make  sure  we  can  always  execute  remote  clients 

case  $DISPLAY  in 

unix : 0.0 | unix: 0 | : 0 . 0 | :0)DISPLAY="$cpu:0"; ; 

esac 

export  DISPLAY 

# Load  resource  definitions  from  .Xresources 
xrdb  -Dhostname=$cpu  $ HOME/ . Xresources 

# Set  keyclick  off  and  invoke  the  screen  saver  after 

# seven  minutes  of  idleness 

xset  c off  s 420 

# Start  the  twm  window  manager 
twm  & 

# Now  start  up  some  xterms 

# Start  an  xterm  in  bottom  left  corner 
xterm  -geometry  80x35+0-0  -display  $DISPLAY  & 

# xterm  next  to  it  across  the  bottom 

xterm  -geometry  80x35+500-0  -display  $DISPLAY  & 

# remote  xterm  in  regular  size  just  above,  but  below  console  xterm 

# at  top 

rsh  ora  xterm  -geometry  -0-0  -display  $DISPLAY  & 

# Now  start  up  other  clients 

# digital  xclock  in  upper  right  corner 
xclock  -digital  -update  1 -geometry  -0+0  & 

# xcalc  just  below  it;  xclock  30  pixels  high  on  sun,  so  offset  by  30 
xcalc  -geometry  -0+30  & 

txload  235  pixels  below  that,  at  bottom  of  xcalc 
xload  -geometry  -0+265  & 

#xbiff  down  another  120  pixels 
xbiff  -geometry  -0+385  & 

# Start  a console  xterm  window. 

# This  is  the  only  xterm  that  should  be  run  in  the  foreground. 

# Killing  this  window  will  shut  down  X. 

# Use  the  following  line  with  xinit;  comment  out  if  you  use  xdm 
exec  xterm  -C  -display  $DISPLAY  -geometry  80x5+0+0 

# Uncomment  this  line  if  you  use  xdm 

# exec  xterm  -C  -Is  -display  $DISPLAY  -geometry  80x5+0+0 
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Figure  A- 1.  Display  after  running  sample  script 

Note  that  all  programs  that  create  windows  (and  hence  don’t  run  quickly  and  then  go  away) 
are  run  in  the  background,  with  the  exception  of  the  final  xterm  window.  This  will  cause  the 
script  to  simulate  the  behavior  of  the  console  xterm  normally  started  by  xinit  or  xdm. 

The  -C  option  specified  with  the  console  xterm  window  redirects  messages  sent  to  /dev/con- 
sole to  that  xterm  window.  This  option  is  only  supported  in  some  implementations  of  X;  see 
your  documentation.  For  additional  information,  see  the  section  “Console  Messages”  later  in 
this  appendix. 

You  may  want  to  start  the  console  xterm  window  as  an  icon,  using  the  -iconic  option,  so 
you’re  less  likely  to  terminate  the  window  inadvertently  and  end  the  session.  If  you  do  this, 
you  should  specify  the  position  of  the  icon  in  your  resource  file.  The  following  resource 
entry  would  place  the  icon  at  coordinates  50,50: 

xterm* iconGeometry : +50+50 

In  the  example,  though,  we  simply  make  the  window  only  five  lines  high,  so  that  we  can  still 
see  console  messages,  but  won’t  be  tempted  to  use  it  for  most  purposes. 

Note  that  if  you  are  using  xdm,  you  want  to  run  the  final  x term  with  the  -Is  option,  to  make 
that  window  be  your  login  shell.  If  you  are  using  xinit,  you  should  definitely  not  use  this 
option!  Since  xinit  is  invoked  from  the  end  of  the  .login  file  (instead  of  directly  by  xdm 
before  login),  you  will  end  up  in  an  infinite  loop. 

Note  that  windows  are  actually  arranged  in  a “tiled”  fashion,  with  two  large  xterms  side  by 
side  on  the  bottom  of  the  screen,  a smaller  one  (connected  to  a remote  system)  above,  and  the 
“desk  accessories”  lined  up  in  the  upper  left  comer.  This  leaves  some  room  free  for  new  win- 
dows or  for  invoking  the  Twm  menu  on  the  root  window.  This  is  ideal  for  our  purposes, 
which  are  mainly  editing,  formatting,  and  testing  examples  for  books.  Depending  on  what 
you  do,  another  arrangement  might  be  better.* 

♦Note  that  this  file  was  developed  for  and  run  on  a Sun  workstation.  Differences  in  pixel  sizes  may  make  the  coordi- 
nates and  sizes  of  various  windows  come  out  differently  on  other  hardware. 
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Starting  X 


In  Chapter  2 Getting  Started , we  described  how  to  start  X manually.  However,  on  a single- 
user  workstation  (or  perhaps  on  several  connected  displays),  it  is  likely  that  you  might  want 
X to  come  up  automatically.  In  many  commercial  X ports,  this  may  already  have  been  done 
for  you. 

This  section  describes  three  ways  to  run  X automatically.  The  first  method  involves  the  dis- 
play manager,  x dm,  which  can  run  X on  a single  display  or  several  connected  displays.  Since 
the  display  manager  is  the  recommended  method  of  running  X and  is  extremely  flexible, 
we’re  including  a fairly  detailed  discussion  of  it.  The  second  method  is  to  use  xinit , which 
was  introduced  in  Chapter  2.  For  those  who  are  still  running  Release  3,  we’ve  included  a dis- 
cussion of  a third  method  that  runs  X from  letclttys  (on  BSD  4.3  systems  only).  This  method 
has  been  phased  out  in  Release  4. 

Starting  X with  the  Display  Manager,  xdm  (Release  4) 

Introduced  in  Release  3,  the  display  manager,  xdm , offers  an  alternative  to  running  X with 
xinit  (or  by  the  obsolete  method,  from  letclttys).  xdm  is  designed  to  run  the  X server  from  the 
letclrc  system  startup  file.  In  its  most  basic  implementation,  the  display  manager  emulates  a 
login  or  getty  on  a standard  terminal,  keeping  the  server  running,  prompting  for  a user’s  name 
and  password,  and  managing  a standard  login  session. 

However,  xdm  has  far  more  powerful  and  versatile  capabilities.  Users  can  design  their  own 
login  sessions,  using  jxsession  files.  You  can  also  customize  special  xdm  files  to  manage  sev- 
eral connected  displays  (both  local  and  remote),  and  to  set  system-wide  and  user-specific  X 
resources. 

A not  so  obvious  limitation  of  xdm  is  that  it  does  not  work  well  if  you  are  using  other  window 
systems  (in  addition  to  X).  If  you  want  to  use  multiple  window  systems  on  the  same  hard- 
ware, you  should  continue  to  use  xinit  for  the  time  being.  Future  releases  of  xdm  should 
overcome  these  limitations. 

The  functionality  of  xdm  has  been  expanded  in  Release  4,  though  many  features  have  not 
changed  since  Release  3.  The  following  sections  describe  the  Release  4 version  of  xdm. 
Release  4 specific  features  are  noted.  If  you  are  running  Release  3,  also  read  the  section 
“Release  3 xdm”  later  in  this  appendix. 

First,  we’ll  give  you  the  basics  of  using  xdm  to  run  X on  a single  display  and  then  give  you 
some  tips  on  how  to  design  your  own  user  session  and  manage  multiple  displays. 
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Getting  Started  with  xdm  on  a Single  Display 

To  have  xdm  run  X on  a single  display,  the  system  administrator  should  perform  three  simple 
tasks: 

1.  Set  up  the  xdm  configuration  file  and  other  special  files,  as  described  in  the  next  section. 

2.  Put  the  line  lusrlbinlXllIxdm  at  the  end  of  /etc/rc  or  other  similar  system  startup  file. 

3.  It’s  also  a good  idea  to  turn  off  the  “console”  in  letclttys  on  a single-user  workstation, 
although  this  is  discretionary.  (As  we’ll  see,  the  display  manager  provides  its  own  login 
window.  Turning  off  the  console  prevents  the  standard  UNIX  prompt  from  being  simulta- 
neously displayed  on  the  full  screen  when  xdm  is  started.  Keep  in  mind  this  will  also  pre- 
vent system  messages  from  being  sent  to  the  console  but  they  should  still  be  saved  in 
h isr/adm!  messages.)  How  you’d  turn  off  the  “console”  depends  on  the  version  of  UNIX 
you  are  running.  The  procedure  and  the  system  file  you  edit  may  differ  from  system  to 
system.  See  the  getty(S)  and  imt{ 8)  reference  pages  in  your  UNIX  documentation  for 
details. 

Once  you  perform  these  steps,  as  long  as  UNIX  is  running,  xdm  should  keep  the  X server  run- 
ning, allow  users  to  log  on  and  off,  and  manage  a simple  login  session. 

The  following  sections  describe  the  steps  you  need  to  get  started  with  xdm  in  greater  detail. 

Setting  Up  the  Configuration  File  and  Other  Special  Files 

In  order  to  run  X,  xdm  uses  a configuration  file  and  several  special  files  that  specify  such 
things  as  the  server,  basic  login  session,  and  an  error  log  file. 

Be  aware  that  xdm  should  be  able  to  work  in  a very  rudimentary  fashion  without  any  special 
files.  However,  a problem  with  Release  4 may  require  that  at  least  two  of  the  special  files  be 
present  (namely,  xdm-config  and  Xservers).  These  limitations  should  be  removed  by  patches 
to  the  release.  If  this  bug  has  been  patched  and  xdm  finds  no  special  files,  it  will  still  start  the 
server  and  a login  xterm  window.  This  default  action  can  be  very  helpful,  because  it  allows 
you  to  log  in  even  if  the  special  files  have  been  inadvertently  removed  or  corrupted. 

Despite  the  potential  to  work  in  a rudimentary  fashion  without  special  files,  xdm  was  not 
intended  to  be  run  in  this  way.  For  most  purposes,  system  administrators  will  want  to  use  and 
very  likely  customize  the  special  files  to  have  xdm  run  X in  a manner  more  suitable  for  the 
particular  system. 

The  configuration  file  and  some  prototypical  special  files  can  be  found  in  the  config  directory 
under  the  xdm  source  directory.  (Starting  from  the  top  of  the  XI 1 source  tree,  the  directory  is 
mit!  clients! xdm!  config .)  Table  A-l  lists  some  of  the  more  commonly  used  special  files  for 
Release  4: 
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Table  A-1.  xdm  Special  Files 


File 

What  it  specifies 

xdm-config 

Configuration  parameters. 

Xservers 

List  of  displays  to  manage. 

xdm-errors 

xdm  error  log  file. 

xdm-pid 

Contains  ID  of  the  xdm  parent  process 
(Release  4 only). 

Xresources 

Resources  to  load  (with  xrdb). 

Xsession 

Default  login  session. 

Xstartup 

Startup  procedure. 

Xreset 

Reset  procedure. 

As  you  can  see,  the  file  xdm-pid  has  been  added  in  Release  4;  it  represents  new  functionality. 
The  Xstartup  and  Xreset  files  can  still  be  used  to  affect  xdm  in  Release  4,  but  there  are  no 
default  files.  We’ll  discuss  these  and  some  of  the  other  special  files  in  greater  detail  later  in 
this  appendix. 


Each  of  the  special  files  can  be  specified  by  an  xdm  command  line  option.  However,  it’s 
more  efficient  to  specify  the  files — other  than  the  single  xdm  configuration  file — as  resources 
and  put  those  resources  in  the  configuration  file  itself.  The  configuration  file  shipped  with  the 
standard  version  of  X is  called  xdm-config.  The  Release  4 version  of  this  file  is  shown  in 
Figure  A-2: 


DisplayManager . servers : 
DisplayManager . errorLogFile : 
DisplayManager . pidFile : 
DisplayManager*resources : 
DisplayManager ‘session : 
DisplayManager ._0 . authorize : 
DisplayManager ‘authorize : 


/usr/lib/Xll/xdm/Xservers 
/usr/lib/Xll/xdm/ xdm-errors 
/usr/lib/Xl 1/xdm/ xdm-pid 
/usr/ lib/Xl 1/xdm/Xre sources 
/usr/1 ib/Xl 1 /xdm/Xsession 
true 
false 


Figure  A-2.  Default  xdm-config  file,  Release  4 

The  following  three  xdm-config  file  entries  have  been  added  in  Release  4: 

DisplayManager .pidFile : /usr/1 ib/Xl 1/xdm/ xdm-pid 

DisplayManager .0 . authorize : true 

DisplayManager*authorize : false 

These  entries  represent  new  xdm  functionality,  which  will  be  discussed  later  in  this  appendix. 
If  you  are  using  Release  3,  these  entries  are  not  applicable.  (See  “Release  3 xdm”  for  the 
appropriate  xdm-config  file.) 


In  effect,  most  of  the  entries  in  the  default  configuration  file  are  just  pointers  to  the  other  spe- 
cial files  xdm  uses.  Notice  also  that,  in  most  cases,  the  configuration  file  has  the  same  syntax 
as  any  resource  file.  Release  4 introduces  a variation  from  traditional  resource  syntax,  which 
appears  in  the  following  line: 

DisplayManager .0 . authorize : true 


System  Management 


533 


System 

Management 


when  you  specify  a display  name  on  the  command  line).  This  is  because  dots  and  colons 
have  special  meaning  for  the  resource  manager.  (Dots  separate  resource  variable  compo- 
nents; a colon  signals  the  end  of  the  variable  and  the  beginning  of  the  value  field.  See  Chap- 
ter 9,  Command  Line  Options  for  more  information.)  Underscores  allow  a display  name  to 
be  treated  as  a single  resource  variable  component  This  syntax  variance  is  applicable  only 
to  Release  4.  The  Release  3 version  of  xdm  compensates  for  resource  syntax 
anomalies — display  name  components  are  separated  by  dots. 

In  addition  to  the  variables  set  in  the  default  xdm-config  file,  you  can  specify  several  other 
display  manager  resources  in  the  configuration  file.  See  the  xdm  reference  page  in  Part  Three 
of  this  guide  for  a complete  list  of  resource  variables. 

To  get  started  using  xdm,  the  system  administrator  should  make  a directory  (/usr/lib/Xl  1/xdm 
is  suggested)  and  copy  these  default  special  files  into  it: 

• xdm-config. 

• Xresources. 

• Xsession. 

As  we’ll  see  later,  each  of  the  standard  files  can  be  customized  but  in  many  cases  the  defaults 
will  be  sufficient  to  run  X on  a single  display.* 

Next,  the  system  administrator  should  create  an  Xservers  file  containing  an  entry  for  the  local 
display.  As  we’ve  said,  if  the  Release  4 xdm  has  been  updated  with  all  relevant  patches,  the 
Xservers  file  is  not  necessary  for  xdm  to  run  X on  a single  display.  However,  if  you  are  run- 
ning Release  4 without  the  relevant  patches,  xdm  has  a bug  that  requires  you  to  set  up  an 
Xservers  file  before  xdm  can  work  properly.  (The  bug  also  requires  an  xdm-config  file  be 
present)  Since  setting  up  an  Xservers  file  is  fairly  simple  to  do  and  a good  way  to  avoid 
potential  problems,  we  recommend  that  you  do  so  before  placing  the  xdm  command  in  one  of 
the  system  startup  files. 

Most  workstations  can  be  run  using  an  Xservers  file  made  up  of  this  line: 

:0  local  /usr/bin/Xll/X 

This  Xservers  file  is  probably  adequate  for  most  workstations.  However,  if  X does  not  run 
properly  on  your  single  display,  you  should  edit  the  Xservers  file.  See  “The  Xservers  File” 
later  in  this  appendix  and  the  xdm  reference  page  in  Part  Three  of  this  guide  for  more  infor- 
mation about  file  syntax. 


*For  our  purposes,  we  are  talking  about  the  default  special  files  provided  with  the  standard  release  of  X.  Keep  in 
mind  that  you  can  rewrite  the  resource  definitions  in  the  xdm-config  file  to  specify  files  of  any  name  (in  any  directory) 
as  the  so-called  special  files.  (The  configuration  file  also  can  have  any  name  you  like  and  be  stored  in  any  directory). 
If  you  use  a filename  other  than  xdm-config , you  need  to  specify  that  filename  (and  its  explicit  path)  with  the 
— con  fig  option  after  the  xdm  command.  See  the  xdm  reference  page  in  Part  Three  of  this  guide  for  more  informa- 
tion.) 
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The  Standard  Login  Session 

Once  you  copy  the  special  files  to  lusr/lib/Xl  1/xdm  and  create  a single-entry  Xservers  file,  if 
you  want  xdm  simply  to  run  the  X server  on  the  local  display,  prompt  for  username  and  pass- 
word, and  run  a simple  login  session,  you  should  be  able  simply  to  add  this  line  to  the  end  of 
the  letclrc  file: 

/usr/bin/Xl 1/xdm 

(Depending  on  your  version  of  UNIX,  you  may  want  to  add  this  line  to  letclrc. local,  Ietclrc2 
or  some  other  file.  Consult  your  operating  system  documentation.  Regardless  of  the  file  to 
which  it  is  added,  the  display  manager  should  be  the  last  process  run.) 

After  this  simple  modification,  when  UNIX  is  put  into  multi-user  mode,  xdm  automatically 
starts  the  X server  and  keeps  it  running. 

xdm  also  takes  over  the  login  procedure  for  displays  specified  in  the  Xservers  file,  supplying 
username  and  password  prompts  normally  provided  by  the  getty  and  login  programs.  With- 
out modification,  xdm  provides  the  login  window  pictured  in  Figure  2-2  of  Chapter  2,  Getting 
Started. 

This  login  procedure  is  controlled  by  the  authentication  widget  (part  of  the  xdm  program), 
which  in  effect  “authenticates”  the  user  and  password.  You  can  customize  the  login  window 
by  setting  resources  for  the  authentication  widget  in  the  Xresources  file.  (These  resources 
must  be  set  in  the  Xresources  file  in  the  directory  lusrllib/Xl  1/xdm  to  take  effect.  They  can- 
not be  set  in  a resources  file  in  a user’s  home  directory,  since  that  file  is  not  loaded  into  the 
resource  manager  until  after  the  login  procedure.)  Among  the  customizable  features  arc  the 
login  greeting  (by  default,  Welcome  to  the  X Window  System),  the  size  and  position  of  the 
window,  and  colors  and  fonts  of  the  text  displayed  or  typed  in  the  window.  See  the  xdm  ref- 
erence page  in  Part  Three  of  this  guide  for  a complete  list  of  resources. 

Each  time  a user  successfully  logs  on,  xdm  looks  for  a file  called  jcsession  in  the  user’s  home 
directory.  If  that  file  exists  and  is  an  executable  script,  xdm  runs  it  as  the  user’s  login  session. 
The  jcsession  file  should  follow  the  general  guidelines  for  startup  scripts  described  earlier  in 
this  appendix. 

If  you’ve  just  set  up  xdm,  users  may  not  have  written  jcsession  scripts.  If  xdm  finds  no  jcses- 
sion file  in  a user’s  home  directory,  it  provides  a default  session,  consisting  of  the  following 
commands  (excerpted  from  the  standard  Xsession  file): 

resources=$HOME/ .Xresources 
xrdb  -load  $resources 

twm  & 

exec  xterm  -geometry  80x24+10+10  -Is 

This  default  session  has  three  elements:  First,  xdm  checks  the  user’s  home  directory  for  a file 
called  Xresources.  If  that  file  exists,  it  is  loaded  into  the  resource  manager  with  xrdb.  Sec- 
ond, the  window  manager,  twm,  is  started.  Third,  the  console  xterm  window  is  started  with  a 
login  shell  (-Is)  in  the  foreground. 

After  this  basic  session  has  been  started,  the  screen  looks  something  like  Figure  2-3  and  the 
user  is  ready  to  work. 
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The  display  manager  can  do  far  more  than  run  the  simple  session  described  above.  Any  of 
the  special  files  can  be  edited  to  customize  the  display  manager  for  your  site.  For  example, 
by  editing  the  Xservers  file,  you  can  set  up  xdm  to  run  multiple  displays,  such  as  X 
terminals.* 

Remember  that,  if  xdm  has  been  modified  with  the  proper  Release  4 patches,  none  of  the  spe- 
cial files  (not  even  the  xdm-config  file)  is  absolutely  necessary  to  run  X on  a single  display. 
In  a worst  case  scenario— if  all  the  special  files  are  removed  or  corrupted—  xdm  has  reason- 
able defaults  that  will  allow  you  to  log  in  and  work.  Depending  on  your  system  configura- 
tion, you  may  elect  not  to  use  some  of  the  special  files.  For  example,  the  Release  4 xdm 
works  well  without  Xstartup  and  Xreset  files  in  many  environments.  As  we’ve  said,  if  no 
Xsession  is  specified,  xterm  is  executed,  etc.  (If  you  decide  not  to  use  one  of  the  special  files 
listed  in  the  default  xdm-config  file,  remember  to  remove  the  pointer  to  it  from  the  file!) 

What  the  special  files  provide  is  the  flexibility  to  configure  xdm  for  your  site,  perhaps  running 
X on  several  displays,  each  possibly  with  a different  default  session,  different  resources  for 
the  authentication  widget,  etc. 

If  you  examine  the  default  configuration  file,  you’ll  notice  most  of  the  resources  are  specified 
with  loose  bindings.  This  means  that  the  specified  resource  (for  example,  Xsession ) will 
apply  to  all  displays  being  run  by  xdm.  By  using  tight  bindings  in  the  configuration  file,  you 
can  also  specify  resources  that  only  take  effect  on  a specific  display.  To  specify  a resource 
for  a particular  display,  just  insert  the  name  of  the  display  between  DisplayManager  and 
the  final  resource  variable.  For  example,  say  xdm  is  running  X on  a workstation  (named  : 0) 
and  a connected  X terminal  (visual : 0).  You  could  specify  two  different  default  sessions 
by  using  resource  definitions  (in  the  configuration  file)  similar  to  the  following: 

DisplayManager . 0 . session : / usr/lib/Xl 1/xdm/Xsession  . ws 

DisplayManager . visual_0 .session:  /usr/lib/Xl 1/xdm/Xsession .visual 

Note  that  an  xdm  resource  specification  uses  an  underscore  in  place  of  the  colon  in  a display 
name.  (As  discussed  earlier,  the  use  of  underscores  has  been  introduced  in  Release  4.  The 
Release  3 syntax  is  discussed  in  the  section  “Release  3 xdm”  later  in  this  appendix.)  You 
should  match  the  display  name  syntax  for  resources  intended  to  be  used  on  the  same  display. 
For  example,  you  might  have  the  following  resources  variable  settings  to  match  the 
session  resource  specifications  above: 

DisplayManager .0. resources:  /usr/1 ib/Xl 1 / xdm/ Xre sources . ws 
DisplayManager . visual  0 .resources : /usr/1 ib/Xl 1/ xdm/ Xre sources .visual 

The  following  sections  discuss  some  possible  customizations  of  the  default  special  files. 
With  the  vast  number  of  possible  system  configurations  and  user  preferences,  you  should 
consult  the  xdm  reference  page  in  Part  Three  of  this  guide  for  more  information. 


♦Generally,  this  modification  is  required  for  xdm  to  run  sessions  on  X terminals.  However,  as  we’ll  see,  an  increas- 
ing number  of  X terminals  do  not  require  an  Xservers  file  entry  in  order  to  be  controlled  by  xdm.  See  “X  Terminals 
and  the  XDM  Control  Protocol  (Release  4)"  later  in  this  appendix. 
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The  Xservers  File 


The  Release  4 xdm  source  directory  contains  two  sample  Xservers  files,  Xservers.ws  and 
Xservers.fs , which  illustrate  file  entries  for  workstations  and  file  servers  (such  as  X 
terminals),  respectively.  To  run  xdm  on  a single  workstation,  you  should  create  an  Xservers 
file  using  the  Xservers.ws  file  as  a guide.  As  we’ll  see  later,  in  most  circumstances,  you  must 
edit  the  Xservers  file  to  specify  additional  displays  for  x dm  to  manage. 

Each  entry  in  the  Xservers  file  usually  has  three  or  four  elements:  the  display  name,  an 
optional  display  class,  the  display  type,  and  the  server  program  name  (and  its  arguments,  typ- 
ically the  display  number).  (Since  an  X terminal  runs  its  own  server,  the  final  argument  can 
be  a comment,  such  as  “Joe’s  X terminal.”)  Possible  display  types  are  described  on  the  xdm 
reference  page  in  Part  Three  of  this  guide. 

Most  workstations  have  a single  display  numbered  0 of  the  type  local , as  illustrated  by  the 
typical  Xservers  file  entry  for  a workstation: 

:0  local  /usr/bin/Xl 1 /X 

The  display  class  part  of  the  Xservers  entry  is  new  as  of  Release  4.  The  sample  entry  above 
does  not  contain  a display  class,  but  it  would  normally  be  the  second  part,  between  the  dis- 
play name  and  type,  as  in  the  following: 

:0  displayclass  local  /usr/bin/Xll/X 

The  display  class  is  determined  by  the  machine  you  are  using  and  should  be  provided  by  the 
hardware  vendor.  The  use  of  the  display  class  is  related  to  an  underlying  feature  of  the 
Release  4 xdm , the  X Display  Manager  Control  Protocol  (XDMCP),  which  is  described  later 
in  this  appendix.  For  now,  suffice  it  to  say  that,  in  most  circumstances,  you  do  not  have  to 
supply  a class  name  within  an  Xservers  file  entry. 

For  xdm  to  run  sessions  on  most  X terminals,  you  must  add  specifications  for  these  displays 
to  the  Xservers  file,  using  the  sample  file  Xservers.fs  from  the  xdm  source  directory  as  a tem- 
plate. For  instance,  say  you  have  two  X terminals  hooked  up  to  a workstation.  (As  of 
Release  4,  most  X terminals  are  of  the  display  type  foreign.  In  Release  3,  most  X terminals 
are  of  the  display  type  transient.)  Your  Xservers  file  might  look  like  this: 

:0  local  /usr/bin/Xl 1 /X 
visual :0  foreign  Lucy's  Visual 
ncd:0  foreign  Ricky's  NCD16 

Notice  that  the  final  element  of  each  X terminal  entry  is  a comment.  Using  this  Xservers  file, 
xdm  provides  login  windows  on  the  two  X terminals,  as  well  as  the  workstation,  and  runs  a 
session  for  any  user  who  logs  on. 

If  you  edit  the  Xservers  file  while  the  server  is  running,  xdm  will  not  be  aware  of  the  changes. 
You  can  make  xdm  reread  the  Xservers  file  (or  another  file  specified  by  the  resource 
DisplayManager . servers)  by  sending  the  xdm  parent  process  a SIGHUP.  Use  the 
UNIX  kill  command  with  the  -HUP  option  (for  SIGHUP)  and  the  process  ID  number  of  xdm. 

It’s  likely  there  will  be  multiple  x dm  processes,  since  the  program  forks  a child  process  for 
every  display  it’s  managing.  As  of  Release  4,  the  ID  of  the  parent  process  is  stored  in  the  file 
specified  by  the  resource  DisplayManager . pidFile — usually  lusr/lib/Xl  1 /xdm/xdm- 
pid. 
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% kill  -HUP  process-ID 

If  a new  entry  has  been  added,  the  display  manager  starts  a session  on  that  display.  If  an 
entry  has  been  removed,  the  display  manager  terminates  any  session  on  that  display  without 
notice  and  no  new  sessions  will  be  started. 

Once  you  edit  the  Xservers  file  to  reflect  the  different  displays  you  want  to  manage,  you  can 
enter  other  display-specific  resources  in  the  configuration  file. 

Be  aware  that  communication  problems  can  arise  between  the  display  manager  and  many 
autonomous  displays  (primarily  X terminals).  If  the  main  display  is  powered  off  or  reset, 
xdm  may  not  detect  that  the  server  has  been  stopped  and  restarted,  and  thus  may  not  send  new 
login  windows  to  connected  displays.  In  the  spring  of  1989,  the  X Consortium  proposed  a 
standard  protocol  between  displays  and  display  managers  that  would  avert  these  problems. 
The  X Display  Manager  Control  Protocol  (XDMCP)  has  been  adopted  and  is  implemented  by 
the  Release  4 xdm , but  not  all  X terminals  implement  it  yet.  We’ll  discuss  the  goals  of  this 
protocol  at  greater  length  in  “X  Terminals  and  the  XDM  Control  Protocol”  later  in  this 
appendix.  For  now,  be  aware  that  the  XDMCP  will  eventually  eliminate  the  need  for 
Xservers  file  entries  for  X terminals.  Currently,  however,  chances  are  that  your  X terminal 
does  not  understand  the  XDMCP  and  requires  an  Xservers  file  entry. 

The  Xsession  File  and  .xsession  Scripts 

Depending  on  the  needs  of  your  site,  you  can  edit  the  Xsession  file  to  make  the  default  ses- 
sion anything  you  want.  You  can  specify  an  alternative  window  manager,  perhaps  even  use 
another  program  to  load  resources,  and  execute  any  combination  of  clients. 

Another  strength  of  xdm  is  that  it  provides  for  each  user  to  design  his  own  jesession  file.  See 
“A  Startup  Shell  Script”  earlier  in  this  appendix  for  more  information  on  writing  a jesession 
file. 

Be  aware  that  if  you’re  testing  a jesession  script  and  it  doesn’t  work,  by  default  xdm  will  not 
let  you  log  in  (using  the  normal  method)  to  fix  it.  However,  xdm  does  provide  an  escape 
hatch  for  these  situations,  which  is  explained  in  ‘The  Xresources  File”  below. 


The  Xresources  File 

The  Xresources  file  is  where  you  should  specify  resources  for  the  authentication  widget.  See 
the  xdm  reference  page  in  Part  Three  of  this  guide  for  a complete  list  of  resource  variables. 

As  of  Release  4,  the  default  Xresources  file  contains  the  following  event  translations,  which 
allow  users  to  log  in  if  a .xsession  script  doesn’t  work: 

x log in* login . translations : #override\ 

<Key>Fl:  set-session-argument (failsafe)  f inish-f ield  ( ) \n\ 
<Key>Return:  set-session-argument ( ) f inish-f ield  ( ) 

This  translation  table  specifies  that  if  you  type  the  FI  key  (rather  than  Return)  after  your 
password  when  logging  in,  a “failsafe”  session,  consisting  of  a simple  login  xterm  window, 
will  be  executed.  This  will  enable  you  to  edit  the  non-functioning  jesession  file.  See  the 
xdm  reference  page  in  Part  Three  of  this  guide  for  more  information.  (See  Chapter  9,  Setting 
Resources,  and  Appendix  H,  Translation  Table  Syntax,  for  a discussion  of  event  translations.) 
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The  Error  Log  File 

xdm  errors  are  normally  printed  to  the  console.  It’s  wise  to  redirect  them  to  a file.  The 
default  configuration  file  sets  the  resource  DisplayManager . errorLogFile  to 
lusr/lib/Xl  1 /xdm/xdm-errors . The  xdm-errors  file  can  be  very  helpful  if  you  are  testing  vari- 
ous xdm  configurations. 

The  xdm-pid  File  (Release  4 Only) 

Added  to  xdm  as  of  Release  4,  the  xdm-pid  file  stores  the  ID  number  of  the  x dm  parent  pro- 
cess. If  you  edit  the  Xservers  file  while  the  server  is  running,  xdm  will  not  be  aware  of  the 
changes.  You  can  make  xdm  reread  the  xdm-config  file  and  the  Xservers  file  (or  another  file 
specified  by  the  resource  DisplayManager.  servers)  by  sending  the  xdm  parent  pro- 
cess a SIGHUP. 

To  make  xdm  aware  of  changes  to  the  Xservers  file,  use  the  UNIX  kill  command  with  the 
-HUP  option  (for  SIGHUP)  and  the  process  ID  number  of  xdm  stored  in  the  xdm-pid  file.  (See 
‘The  Xservers  File”  earlier  in  this  appendix  for  an  example.) 

Xstartup  and  Xreset 

As  stated  previously,  the  Xstartup  and  Xreset  files  mentioned  in  Table  A-l  can  still  be  used  to 
affect  xdm  in  Release  4,  but  there  are  no  default  files;  thus,  they  are  not  specified  in  the 
default  configuration  file. 

The  Xstartup  file  is  intended  to  be  a script  that  is  run  as  root  before  starting  the  user  session. 
You  might  want  to  write  a script  containing  commands  to  make  fake  entries  in  /etc/utmp, 
mount  users’  home  directories  from  file  servers,  display  a message  of  the  day,  or  abort  the 
session  if  logins  are  not  currently  allowed. 

The  Xreset  file  is  intended  to  be  a script  that  is  run  as  root  after  a user  session  has  been  ended. 
You  might  want  to  write  a script  to  undo  the  effects  of  commands  in  Xstartup , perhaps 
removing  fake  entries  from  / etc/utmp,  or  unmounting  directories  from  file  servers. 

See  the  xdm  reference  page  for  more  information  about  the  Xstartup  and  Xreset  files. 

Security  and  the  authorize  Resource  (Release  4 Only) 

In  addition  to  pointers  to  several  special  files,  the  xdm-config  file  contains  the  following 
resource  specifications: 

DisplayManager .0 . authorize : true 

DisplayManager*authorize : false 

Available  as  of  Release  4,  the  authorize  resource  represents  a new  method  of  security  for 
X,  which  xdm  can  be  set  up  to  provide.  The  first  resource  specification  above  sets  a user- 
based  server  access  scheme  to  work  on  the  local  display.  The  second  one  turns  the  scheme 
off  on  all  other  displays.  These  defaults  should  be  compatible  with  running  X on  the  local 
display  and  most  X terminals  that  might  be  connected  to  it.  See  “User-based  Access:  xdm 
and  the  .Xauthority  File”  later  in  this  appendix  and  the  xdm  reference  page  in  Part  Three  of 
this  guide  for  more  about  authorization. 
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Stopping  xdm  and  the  Server 


By  default,  xdm  automatically  restarts  the  server  if  the  server  is  killed.  If  you  don’t  want  this 
boomerang  effect,  set  the  following  resource  in  the  xdm-config  file: 

DisplayManager .DISPLAY. terminateServer:  true 

Then  if  you  kill  the  server  and  all  xdm  processes,  X will  exit. 

X Terminals  and  the  XDM  Control  Protocol  (Release  4) 

The  X Display  Manager  Control  Protocol  (XDMCP),  introduced  at  Release  4,  facilitates  the 
connection  of  X terminals  to  remote  hosts  via  xdm.  From  a user’s  standpoint,  the  main 
advantage  of  XDMCP  is  that  it  allows  you  to  turn  an  X terminal  off  and  on  again,  while 
maintaining  the  connection  to  the  remote  host.  When  you  turn  on  an  X terminal,  xdm  should 
automatically  display  a login  window.  The  exchange  of  information  between  the  X terminal 
and  the  remote  host  is  invisible  to  the  user.  In  fact,  XDMCP  and  xdm  are  intended  to  make  X 
terminals  as  easy  to  use  as  traditional  character  terminals.  Under  the  X Display  Manager 
Control  Protocol,  an  X terminal  basically  requests  a connection  to  a remote  host,  is  recog- 
nized by  the  host,  and  is  sent  a login  prompt  by  xdm. 

Prior  to  the  adoption  of  this  protocol,  xdm  was  not  equipped  to  reconnect  to  X terminals  that 
had  been  turned  off  and  on  again.  In  most  cases,  X terminals  had  to  be  left  on  at  all  times.  If 
a terminal  was  turned  off,  it  was  often  necessary  to  kill  the  associated  xdm  process;  xdm 
would  then  restart  itself  and  reestablish  the  connection,  again  displaying  the  login  window. 

XDMCP  is  intended  to  solve  problems  like  this.  Be  aware,  however,  that  the  X terminals  in 
question  must  be  programmed  to  interpret  XDMCP  or  modified  to  do  so.  At  the  time  of 
Release  4,  virtually  no  X terminals  in  the  market  supported  XDMCP.  Protocol-compatible  X 
terminals  should  become  available  in  increasing  numbers  by  the  fall  of  1990.  If  you’re  using 
an  older  X terminal,  chances  are  that  the  programs  controlling  it  must  be  upgraded  to  com- 
municate via  XDMCP. 

If  you  are  using  X terminals  at  your  site,  the  way  you  set  up  x dm  partially  depends  on 
whether  the  terminals  can  communicate  via  the  XDMCP.  If  a terminal  can't  communicate  in 
this  way,  the  Xservers  file  must  include  an  entry  for  it  and  the  terminal  must  be  left  on  at  all 
times  to  maintain  the  connection  to  the  host  via  xdm.  If  a terminal  can  communicate  via  the 
protocol,  no  Xservers  file  entry  is  necessary  and  the  terminal  can  be  turned  on  and  off,  while 
still  maintaining  the  connection  to  the  host.  Refer  your  X terminal  documentation  to  find  out 
whether  it’s  XDMCP  compatible. 

The  XDMCP  helps  clarify  the  actual  purpose  of  the  Xservers  file.  The  file  is  actually  a list  of 
displays  to  which  xdm  must  perpetually  maintain  a connection.  By  contrast,  the  XDMCP  is  a 
dynamic  mechanism  whereby  connections  are  made  when  requested  by  a display,  such  as  a 
workstation  or  a newer  X terminal,  that  can  communicate  via  the  protocol. 

XDMCP  also  affects  the  Xservers  file  entry  for  the  host.  If  you  are  running  Release  4,  it  is 
recommended  that  the  Xservers  file  entry  for  the  host  include  a display  class  name,  which 
should  be  provided  by  the  hardware  manufacturer.  You  can  use  this  name  in  the  xdm-config 
file  to  specify  resources  by  display  class,  rather  than  by  individual  display. 
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Release  3 xdm 


The  Release  3 version  of  xdm  is  somewhat  simpler  to  get  started  with,  albeit  somewhat  less 
powerful,  than  the  Release  4 version.  This  section  highlights  the  Release  3 specifics.  We 
assume  you  have  already  read  the  preceding  sections  describing  the  Release  4 version. 

The  Release  3 xdm  provides  sample  files  that  are  probably  adequate  to  run  X on  most  works- 
tations. (A  sample  Xservers  file  intended  for  use  on  a workstation  is  included  in  the  Release 
3 xdm  source  directory.)  In  order  to  have  xdm  run  X on  a single  display,  simply  perform  the 
following  three  steps: 

1.  Create  a directory  called  lusrlliblXll/xdm.  Copy  the  default  versions  of  the  files  from  the 
config  directory  under  the  xdm  source  directory  into  the  new  directory. 

2.  Put  the  line  lusrlbinlXll/xdm  at  the  end  of  letclrc  or  other  similar  system  startup  file. 

3.  It’s  also  a good  idea  to  turn  off  the  “console”  in  I etc!  ttys  on  a single-user  workstation, 
although  this  is  discretionary.  (Since  the  display  manager  provides  its  own  login  window, 
turning  off  the  “console”  prevents  the  standard  UNIX  prompt  from  being  simultaneously 
displayed  on  the  full  screen  when  xdm  is  started.  Keep  in  mind  this  will  also  prevent  sys- 
tem messages  from  being  sent  to  the  console,  but  they  should  still  be  saved  in 
lusr/adm/messages.)  How  you’d  turn  off  the  “console”  depends  on  the  version  of  UNIX 
you  are  running.  The  procedure  and  the  system  file  you  edit  may  differ  from  system  to 
system.  See  the  getty(8)  and  init( 8)  reference  pages  in  your  UNIX  documentation  for 
details. 

Once  you  perform  these  steps,  so  long  as  UNIX  is  running,  xdm  should  keep  the  X server  run- 
ning, allow  users  to  log  on  and  off,  and  manage  a simple  login  session. 

The  Release  3 xdm  should  be  able  to  run  X on  a single  workstation  without  any  special  files, 
though  it  was  not  intended  to  be  used  in  this  manner.  If  xdm  finds  no  special  files,  it  will  still 
start  the  server  and  a login  xterm  window.  This  default  action  can  be  very  helpful,  because  it 
allows  you  to  log  in  even  if  the  special  files  have  been  inadvertently  removed  or  corrupted. 
For  most  purposes,  however,  system  administrators  will  want  to  use  and  very  likely  custom- 
ize the  special  files  to  have  xdm  run  X in  a manner  more  suitable  for  the  particular  system. 

Release  3 Special  Files  and  the  Config  File 

The  Release  3 xdm  recognizes  most  of  the  same  special  files  and  resources  as  the  Release  4 
version  (see  Table  A-l),  with  the  following  exceptions:  the  xdm-pid  file  and  the  authori- 
zation resource  setting  are  available  in  Release  4 only. 

The  Release  3 version  of  the  xdm- config  file  is  shown  in  Figure  A-3: 
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DisplayManager . servers : 


/usr/1 ib/Xl 1/xdm/Xservers 


DisplayManager . errorLogFile : 
DisplayManager*resources : 


/usr/1 ib/Xl 1/xdm/xdm-errors 
/usr /I ib/Xl 1/xdm/Xresources 


DisplayManager* st art up: 
DisplayManager*reset : 


/usr/1 ib/Xl 1/xdm/Xstartup 
/usr/1 ib/Xl 1/xdm/Xreset 


DisplayManager* session : 


/usr /I ib/Xl 1/xdm/Xsess ion 


Figure  A-3.  Default  xdm-config  file,  Release  3 

The  Release  3 default  Xservers  file,  in  Figure  A-4,  is  probably  adequate  for  most  worksta- 
tions. 

:0  local  /usr/bin/Xl 1/X  :0 
Figure  A-4.  Typical  Xservers  file  for  a workstation,  Release  3 

However,  if  X does  not  run  properly  on  your  single  display,  you  should  edit  the  Xservers  file 
to  reflect  the  local  display  name.  You  must  also  edit  the  Xservers  file  to  specify  additional 
displays  for  xdm  to  manage.  See  “Managing  Multiple  Displays:  the  Release  3 Xservers  File” 
later  in  this  appendix. 

Customizing  the  Release  3 xdm 

Like  the  Release  4 version,  the  Release  3 version  special  files  provide  the  flexibility  to  con- 
figure xdm  for  your  site,  perhaps  running  X on  several  displays,  each  possibly  with  a different 
default  session,  different  resources  for  the  authentication  widget,  etc.  (If  you  decide  not  to 
use  one  of  the  special  files  listed  in  the  default  xdm-config  file,  remember  to  remove  the 
pointer  to  it  from  the  file!) 

Most  of  the  resources  specified  in  the  default  configuration  file  have  loose  bindings,  indicat- 
ing that  the  resource  applies  to  all  displays  being  run  by  xdm.  By  using  tight  bindings  in  the 
configuration  file,  you  can  also  specify  resources  that  only  take  effect  on  a particular  display. 
To  specify  a resource  for  a particular  display,  just  insert  the  name  of  the  display  between 
DisplayManager  and  the  final  resource  variable.  For  example,  say  xdm  is  running  X on 
a workstation  ( : 0)  and  a connected  X terminal  (visual : 0).  You  could  specify  two  differ- 
ent default  sessions  by  using  resource  definitions  (in  the  configuration  file)  similar  to  the  fol- 
lowing: 

DisplayManager. .0. session:  /usr/lib/Xl 1/xdm/Xsession . ws 
DisplayManager . visual . 0 . session  : /usr/1 ib/Xl 1/xdm/Xsession . visual 

Note  that  an  xdm  resource  specification  uses  a dot  in  place  of  the  colon  in  a display  name. 
(This  is  different  from  the  syntax  expected  by  Release  4,  in  which  underscores  are  used 
between  the  parts  of  a display  name.)  You  should  match  the  display  name  syntax  for 
resources  intended  to  be  used  on  the  same  display.  For  example,  you  might  have  the  follow- 
ing resources  variable  settings  to  match  the  session  resource  specifications  above: 

DisplayManager. . 0 . resources : /usr/lib/Xl 1/xdm/Xresources . ws 
DisplayManager . visual . 0 . resources : /usr/lib/Xl 1/xdm/Xresources . visual 
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The  following  sections  describe  Release  3 specific  features  that  may  affect  customization  and 
discuss  possible  customization  of  some  of  the  default  special  files.  You  should  first  have 
read  the  sections  on  customizing  the  Release  4 version  of  xdm  earlier  in  this  appendix.  With 
the  vast  number  of  possible  system  configurations  and  user  preferences,  you  should  also  con- 
sult the  xdm  reference  page  in  Part  Three  of  this  guide  for  more  information. 

Managing  Multiple  Displays:  the  Release  3 Xservers  File 

If  you  are  running  Release  3,  you  must  edit  the  Xservers  file  to  specify  additional  displays  for 
xdm  to  manage. 

In  Release  3,  each  entry  in  the  Xservers  file  has  three  elements:  the  display  name,  the  display 
type,  and  the  server  program  name  (and  its  arguments,  in  most  cases  the  display  number). 
(Since  an  X terminal  uses  a remote  server,  the  third  argument  can  be  a comment,  such  as 
“Ethel’s  X terminal.”) 

Most  workstations  have  a display  numbered  0 of  the  type  local , so  the  Xservers  file  should 
look  like  this: 

:0  local  /usr/bln/Xl 1/X  :0 

You  can  also  add  specifications  for  additional  displays,  such  as  X terminals.  In  Release  3,  X 
terminals  have  the  display  type  transient.  (In  Release  4,  this  has  been  changed  to  foreign.) 
To  add  a single  X terminal,  you  might  create  a file  similar  to  the  following: 

:0  local  /usr/bin/Xl 1/X  :0 

visual:0  transient  Andy's  Visual 

Notice  that  the  third  element  of  the  X terminal  entry  is  a comment.  Using  this  Xservers  file, 
xdm  provides  login  windows  on  the  workstation  and  the  X terminal,  and  runs  login  sessions 
for  any  users  who  log  in. 

Be  aware  that  communication  problems  can  arise  between  the  display  manager  and  many 
displays.  If  the  main  display  is  powered  off  or  reset,  xdm  may  not  detect  that  the  server  has 
been  stopped  and  restarted,  anc  thus  may  not  send  new  login  windows  to  connected  displays. 
The  X Display  Manager  Control  Protocol,  introduced  in  Release  4,  is  designed  to  avert  these 
problems.  (See  “X  Terminals  and  the  XDM  Control  Protocol  (Release  4)”  earlier  in  this 
appendix  for  more  information.)  However,  if  you  are  still  running  Release  3,  the  safest  way 
to  keep  xdm  running  X on  an  X terminal  is  to  leave  the  terminal  on. 

If  you  edit  the  Xservers  file  while  the  server  is  running,  xdm  will  not  be  aware  of  the  changes. 
You  can  make  xdm  reread  the  Xservers  file  (or  another  file  specified  by  the  resource 
DisplayManager . servers)  by  sending  the  xdm  parent  process  a SIGHUP.  Use  the 
UNIX  kill  command  with  the  -hup  option  (for  SIGHUP)  and  the  ID  number  of  xdm' s parent 
process,  as  in  the  following  example: 

% kill  -HUP  process-ID 

It’s  likely  there  will  be  multiple  xdm  processes,  since  the  program  forks  a child  process  for 
every  display  it’s  managing.  As  a general  rule,  send  the  signal  to  the  lowest  numbered  xdm 
process.  (As  we’ve  seen,  in  Release  4,  the  xdm-pid  special  file  contains  the  relevant  process 
ID  number.) 
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If  a new  entry  has  been  added,  the  display  manager  starts  a session  on  that  display.  If  an 
entry  has  been  removed,  the  display  manager  terminates  any  session  on  that  display  without 
notice  and  no  new  sessions  will  be  started. 

If  the  xdm  connection  to  an  X terminal  is  interrupted,  you  should  also  be  able  to  reestablish  it 
by  sending  a SIGHUP  to  the  xdm  parent  process. 

Once  you  edit  the  Xservers  file  to  reflect  the  different  displays  you  want  to  manage,  you  can 
enter  other  display-specific  resources  in  the  configuration  file. 

Release  3 .xsession  Scripts 

Be  warned  that  if  you’re  testing  a jcsession  script  and  it  doesn’t  work,  by  default  x dm  will  not 
let  you  log  in  (under  the  same  login  name)  to  fix  it.  While  the  default  Release  4 version  of 
xdm  provides  an  escape  hatch  for  these  situation,  the  Release  3 version  does  not.  We  strongly 
suggest  that  you  set  one  up  using  ‘The  Xresources  File.” 

Release  3 Xresources  File 

To  give  users  a way  to  log  in  if  a jcsession  script  doesn’t  work,  place  the  following  event 
translations  in  the  Xresources  file: 

xlogin * login . translations : #override\ 

<Key>Fl:  set-session-argument ( failsafe)  f inish-f ield ( ) \n\ 
<Key>Return:  set-session-argument ( ) f inish-f ield ( ) 

This  translation  specifies  that  if  you  type  the  FI  key  (rather  than  Return)  after  your  password 
when  logging  in,  a “failsafe”  session,  consisting  of  a simple  login  xterm  window,  will  be  exe- 
cuted. This  will  enable  you  to  edit  the  non-functioning  jcsession  file.  [This  translation  table 
has  been  added  to  the  default  Xresources  file  in  Release  4.] 

The  Xresources  file  is  also  where  you  should  specify  resources  for  the  authentication  widget. 
See  the  xdm  reference  page  in  Part  Three  of  this  guide  for  a complete  list  of  resource  vari- 
ables. (See  Chapter  9,  Setting  Resources , and  Appendix  H,  Translation  Table  Syntax , for  a 
discussion  of  event  translations.) 

Release  3 Xstartup  and  Xreset 


The  Release  3 version  of  xdm  includes  default  Xstartup  and  Xreset  files  that  contain  nothing 
more  than  a comment.  You  can  use  these  files  to  specify  custom  startup  and  reset  proce- 
dures. See  “Xstartup  and  Xreset”  under  the  discussion  of  the  Release  4 xdm , earlier  in  this 
appendix.  Also  see  the  xdm  reference  page  in  Part  Three  of  this  guide  for  more  information 
about  the  Xstartup  and  Xreset  files. 
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Starting  X with  xinit 


The  xinit  program  is  used  to  start  the  server  and  a first  client  program,  by  default  an  xterm 
window.  Starting  X manually  with  xinit  is  described  in  Chapter  2,  Getting  Started.  You  can 
also  use  xinit  to  start  X automatically. 

The  easiest  way  to  do  this  is  to  run  xinit  from  your  .login  or  .profile  file.  (If  you  are  using 
System  V,  this  may  be  the  only  reliable  way  to  run  xinit) 

xinit  will  look  in  your  home  directory  for  a file  called  ocserverrc  to  run  as  a shell  script  to 
start  up  the  server.  If  there  is  no  such  script,  xinit  will  start  the  server  X on  the  display  : 0. 

xinit  will  also  look  in  your  home  directory  for  a file  called  jxinitrc  to  run  as  a login  script, 
such  as  the  one  described  earlier  in  this  appendix.  If  no  such  script  is  found,  it  will  execute  a 
login  xterm  window. 

With  System  V only,  you  might  try  to  run  xinit  from  the  terminal  initialization  file  /etc/init- 
tab.  This  file  is  analogous  to  the  BSD  4.3  /etc/ ttys.  The  /etc/inittab  file  normally  has  an  entry 
for  each  serial  port  on  a system,  plus  several  entries  that  are  used  during  the  boot  process. 
Note  that  the  concept  of  pseudo-terminals,  or  ptys  (which  X relies  on)  is  foreign  to  System  V. 
All  System  V servers  will  have  had  to  do  some  system  hacking  to  add  support  for  ptys.  How 
this  is  done  will  vary  from  system  to  system.  As  a result,  we’re  going  to  beg  off  on  describ- 
ing inittab  in  detail,  and  refer  you  to  your  system  documentation.  Again,  it  is  also  possible 
that  there  will  be  problems  with  the  controlling  tty. 

See  the  xinit  reference  page  in  Part  Three  of  this  guide  for  more  information. 


An  Older  Method  of  Starting  X:  /etc/ttys 

For  Release  3,  this  method  was  supported  only  for  backwards  compatibility  with  older 
releases  of  X.  As  of  Release  4,  it  is  not  supported.  In  either  case,  system  administrators 
should  switch  to  xinit  or  xdm. 

On  BSD  4.3-derived  systems,  you  can  start  X automatically  from  the  /etc/ ttys  terminal  initial- 
ization file.*  This  file  normally  contains  a list  of  terminals  on  which  a login  prompt  should 
be  printed  by  the  getty  program.  For  X,  this  file  can  be  used  instead  to  start  xterm  for  a 
pseudo-terminal.  A typical  line  to  start  X from  the  /etc/ ttys  file  might  have  the  following 
format: 


•Note  that  the  technique  described  here  will  not  work  on  earlier  BSD  systems,  Xenix,  or  other  systems  which  use  the 
pre-BSD  4.3  ttys  format. 
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BSD  4.3  /etcAtys 


dev  name  command  ttytype 

I 1 . ' 

ttyvO  "/etc/xterm  — L -geometry  -1+1  -display  :0  xterm 

on  secure  window="/usr/bin/Xll/X  :0  — c —1"  #Start  X 

I I 

status  comment 


Field 


Function  in  /etc/ ttys 


devname  The  name  of  the  special  file  in  the  dev  directory  that  corresponds  to  the  device. 
For  X,  the 

pseudo-terminal  with  the  highest  minor  device  number  (e.g.  /dev/ttyqf  and 
/dev/ptyqf)  is  normally  renamed  Idev/ttyvO  and  Idev/ptyvO.  For  systems  with 
more  than  one  display,  the  next  highest  pty  is  used  for  the  second  display,  and  so 
on. 

command  The  command  to  be  run  by  init.  This  is  normally  getty,  but  can  be  another  com- 
mand, such  as  the  command  to  start  a window  system.  In  this  example,  xterm  is 
run  with  the  -L  option,  which  causes  getty  to  be  run  in  the  xterm  window  rather 
than  the  shell.  (The  -L  option  is  not  supported  in  Release  4.)  The  window  is 
placed  in  the  top  right  comer  of  the  screen.  Since  spaces  and  tabs  are  used  to 
separate  fields  in  /etc/ ttys,  the  entire  command  must  be  quoted. 

Note  that  some  implementations  of  init  have  relatively  small  program  name  buf- 
fer sizes,  so  you  may  find  you  can’t  list  many  xterm  options.  In  addition, 
because  the  # character  is  used  as  a comment  symbol  in  /etc/ ttys,  you  may  have 
difficulty  specifying  colors  (say  for  an  xterm  window  background)  using  the  hex- 
adecimal color  syntax.  If  you  run  into  either  of  these  problems,  you  may  want  to 
write  a small  program  that  runs  xterm  with  the  desired  arguments,  and  have  init 
run  that  instead. 

ttytype  The  name  of  the  terminal  attached  to  the  line.  This  should  be  the  name  as 
defined  in  the  /etc/termcap  terminal  database.  In  the  example  above,  it  is  speci- 
fied as  xterm. 

Note  that  the  presence  of  the  terminal  type  field  in  the  BSD  4.3  ttys  replaces  the 
/etc/ ttytype  file  that  was  used  for  this  purpose  in  earlier  BSD  versions. 

status  The  word  on  if  the  command  is  to  be  executed,  or  off  if  it  is  not.  Additional  flags 
may  be  specified  after  on  or  off.  The  word  secure  must  be  present  to  allow  root 
to  log  in  on  a particular  terminal.  The  flag  window ="  command"  specifies  a 
window  system  command  to  be  executed  by  init  before  it  starts  xterm.  This 
should  be  the  command  to  start  the  X server,  as  shown  in  the  example. 

comment  Comments  can  appear  anywhere  in  the  file.  They  are  introduced  by  #,  and  are 
terminated  by  a newline. 
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Server  Access  Control 


X runs  in  a networked  environment.  Because  of  X’s  design,  your  workstation  is  no  longer 
your  private  preserve,  but  hypothetically,  can  be  accessed  by  any  other  host  on  the  network. 
This  is  the  true  meaning  of  the  server  concept:  your  display  can  serve  clients  on  any  system, 
and  clients  on  your  system  can  display  on  any  other  screen. 

The  possibilities  for  abuse  are  considerable.  However,  there  are  two  access  control  mecha- 
nisms, one  host-based  and  one  user-based.  The  host-based  scheme  involves  a system  file 
(/etc/Xn. hosts)  and  can  be  controlled  using  the  xhost  client.  The  user-based  scheme  involves 
authorization  capabilities  provided  by  the  display  manager,  xdm,  as  of  Release  4,  and 
depends  upon  the  newly  introduced  X Display  Manager  Control  Protocol  (XDMCP).  As 
we’ll  see,  since  most  X terminals  cannot  interpret  the  XDMCP  at  this  time,  the  usefulness  of 
this  latter  access  control  mechanism  is  currently  somewhat  limited. 

These  two  access  control  methods  are  discussed  briefly  in  the  following  sections.  For  more 
information,  see  the  Xserver , xhost,  xdm,  and  xauth  reference  pages  in  Part  Three  of  this 
guide. 


Host-based  Access  and  the  xhost  Client 

The  /etc/Xn. hosts  file  (where  n is  the  number  of  the  display)  contains  a list  of  systems  that  arc 
allowed  to  access  the  server.  By  default,  this  file  contains  only  the  name  of  the  local  host. 
Edit  this  file  so  that  it  contains  the  list  of  systems  you  want  to  have  access  to  your  server  on  a 
regular  basis. 

The  xhost  client  can  be  used  to  give  (or  deny)  systems  access  to  the  server  interactively,  pos- 
sibly overriding  the  contents  of  /etc/Xn. hosts.  (The  xhost  client  can  also  be  run  from  a startup 
script.)  Note  that  this  is  really  only  sufficient  for  a single-user  workstation  environment, 
however. 

Specifying  a host  name  (with  an  optional  leading  plus  sign)  allows  the  host  to  access  the 
server,  and  specifying  a host  name  with  a leading  minus  sign  prevents  a previously  allowed 
host  from  accessing  the  server.  Multiple  hosts  can  be  specified  on  the  same  line.  Running 
xhost  without  any  arguments  prints  the  current  hosts  allowed  to  access  your  display. 

For  example,  to  add  the  hosts  jupiter  and  satum,  and  remove  neptune: 

% xhost  +jupiter  satum  -neptune 

It  is  possible  to  remove  the  current  host  from  the  access  list.  Be  warned  that  you  can’t  undo 
this  without  logging  out. 

Note  that  when  a remote  system  is  denied  access  to  your  display,  it  means  two  things:  that  a 
person  working  on  the  remote  system  can’t  display  on  your  screen,  and  that  you  can’t  use 
that  remote  system  for  running  clients  you  want  displayed  on  your  screen. 
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User-based  Access:  xdm  and  the  .Xauthority  File  (Release  4) 


As  of  Release  4,  the  display  manager  and  its  control  protocol  (XDMCP)  provide  a user-based 
access  control  mechanism,  which  can  be  used  to  supplement  or  replace  the  host-based  access 
mechanism  discussed  in  the  previous  section.  The  Release  4 xdm  can  be  set  up  to  provide 
user  authorization  on  a particular  display  (see  “Security  and  the  authorize  Resource”  earlier 
in  this  appendix).  If  authorization  is  enabled,  when  you  log  in,  xdm  places  a machine-read- 
able access  code,  known  as  a magic  cookie , in  a file  called  X authority  in  your  home  direc- 
tory. xdm  also  makes  this  magic  cookie  available  to  the  server. 

The  magic  cookie  defined  in  a user’s  Xauthority  file  is  basically  a secret  code  shared  by  the 
server  and  a particular  user  logged  in  on  a particular  display.  When  the  user  runs  a client  on 
the  local  display,  the  server  checks  to  see  whether  the  client  program  has  access  to  the  magic 
cookie.  All  processes  started  by  the  user  in  question  have  that  access,  and  thus  the  server 
allows  the  client  to  be  run  on  the  display.  Basically,  under  the  magic  cookie  authorization 
scheme,  a display  becomes  user-controlled.  (Once  xdm  creates  an  Xauthority  file  for  a user, 
each  time  the  user  logs  on,  xdm  merges  in  authorization  codes  (magic  cookies).) 

The  access  afforded  by  magic  cookies  is  not  as  broad  as  that  afforded  by  the  host-based 
mechanism.  When  a system  relies  entirely  on  host-based  access,  any  machine  on  the  list  of 
approved  hosts  can  connect  to  the  system.  Thus,  generally,  any  user  logged  on  to  an 
approved  host  can  access  any  display  connected  to  the  system.  This  is  somewhat  feeble  secu- 
rity. User-based  access  control  is  a little  safer. 

Be  aware,  however,  that,  currently,  user-based  access  control  cannot  provide  security  for  all 
X terminal  users.  This  method  of  access  control  relies  on  the  X Display  Manager  Control 
Protocol  and  few  X terminals  in  the  current  market  are  programmed  to  understand  the  proto- 
col. However,  user-based  access  can  be  used  effectively  on  workstations  running  Release  4 
and  on  many  of  the  newer  X terminals. 

The  security  mechanism  provided  by  the  magic  cookie  is  evident  in  a situation  in  which 
another  user  tries  to  run  a client  on  your  machine.  The  server  requires  the  client  run  by  the 
other  user  to  have  access  to  the  magic  cookie  shared  exclusively  between  you  and  the  server. 
The  other  user  cannot  provide  the  proper  authorization  code,  and  thus  cannot  run  a client  on 
your  host. 

Of  course,  in  many  cases,  users  in  a network  will  want  to  run  clients  on  several  machines 
(while  displaying  the  client  window  on  their  local  displays).  This  can  be  done  if  a user  sup- 
plies authorization  information  associated  with  his  local  machine  (or  X terminal  display)  to 
the  remote  host.  X developers  have  provided  a new  client,  xauth,  to  allow  users  to  transfer 
this  information.  Basically,  xauth  is  a utility  to  manipulate  Xauthority  files. 

The  most  common  use  for  xauth  is  to  extract  a user’s  authorization  information  for  the  cur- 
rent display,  copy  it  to  another  machine,  and  merge  it  into  the  server’s  authorization  records 
on  the  remote  machine,  as  in  the  following: 

% xauth  extract  - $D I SPLAY  | rah  ho at 2 xauth  merge  - 

The  dash  (-)  arguments  indicate  that  extracted  authorization  records  should  be  written  to  the 
standard  output  and  that  the  xauth  merge  function  should  accept  records  from  standard  input. 
This  command  supplies  the  remote  server  with  authorization  information,  allowing  the  user 
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to  run  a remote  shell  on  that  host  See  the  xauth  reference  page  in  Part  Three  of  this  guide  for 
more  information. 

If  an  installation  is  using  remote  file  sharing,  such  as  NFS,  then  sharing  authorization  records 
may  not  be  an  issue.  If  every  user  has  a single  home  directory  that  is  accessible  to  all 
machines,  the  machines  have  access  to  the  necessary  Xauthority  files  at  all  times.  In  such  an 
environment,  users  should  be  able  to  run  programs  on  any  of  the  networked  machines  without 
using  xauth. 

When  user-based  access  control  fails  (for  example,  when  a null  or  invalid  magic  cookie  is 
offered  to  the  server),  host-based  access  takes  over.  To  be  more  specific,  say  for  example  a 
user  is  logged  on  at  an  X terminal  that  is  not  XDMCP  compatible,  and  thus  the  user  has  no 
Xauthority  file  (i.e.,  magic  cookie).  If  that  user  tries  to  open  a window  on  the  remote  console 
display,  the  client  window  cannot  access  a magic  cookie.  (The  host  interprets  this  as  a null 
cookie.)  Then  host-based  access  control  takes  over.  If  the  user  in  question  is  working  on  a 
system  authorized  in  the  letc/Xn. hosts  file,  he  should  be  authorized  to  run  a client  on  the  con- 
sole display. 


Font  Management 

In  Release  3,  the  X Consortium  adopted  the  Bitmap  Display  Format  (BDF)  as  the  (non-exclu- 
sive) standard  font  format.  BDF  font  files  must  be  compiled  to  produce  SNF  (Server  Natural 
Format)  font  files,  which  can  be  used  by  the  server.  (These  font  files  have  a .snf  extension.) 

The  standard  fonts  shipped  with  X should  already  be  compiled.  If  you  add  BDF  font  files  to 
the  system,  the  files  must  be  converted  to  SNF  format  using  the  program  bdftosnf.  The 
showsnf  program  displays  the  SNF  font  file  so  you  can  check  that  it  compiled  properly.  See 
the  bdftosnf  and  showsnf  reference  pages  in  Part  Three  of  this  guide  for  details. 

Once  a new  font  is  moved  to  the  directory  you  want  (perhaps  lusr/lib/Xl  1 Ifonts/misc),  you 
must  add  the  font  to  the  font  database  (fonts.dir  file)  used  by  the  server.  To  do  this,  run 
mkfontdir  with  the  directory  as  an  argument,  as  in  the  following: 

% mkfontdir  /usr/lib/Xll/fonts/misc 

An  entry  for  the  new  font  is  added  to  the  fonts.dir  file.  You  should  also  edit  the  fonts.alias 
file  if  you  want  to  add  an  alias  for  the  new  font. 

Then  the  server  must  be  made  aware  of  the  new  font.  The  command: 

% xset  fp  rehash 

makes  the  server  reread  the  font  databases  and  alias  files  in  the  current  font  path. 

If  you  are  using  a server  other  than  the  standard  release,  the  server  developer  should  provide 
a program  to  convert  BDF  font  files  to  a format  appropriate  for  the  server. 
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Console  Messages 


On  a single-user  workstation,  it  is  likely  that  the  screen  used  for  running  X is  also  used  as  the 
system  console. 

If  X is  started  manually,  the  console  will  be  the  first  window  to  appear  on  the  screen.  But  if 
X is  started  from  your  .login  file,  console  messages  from  the  kernel  may  sometimes  appear  on 
the  screen,  overlaying  the  X windows.  They  make  a nasty  mess  of  the  screen,  but  the  display 
can  be  refreshed  and  the  console  message  erased  by  running  the  client  xrefresh  (described  in 
Part  Three). 

Some  implementations  of  X support  a -C  option  to  xterm  that  redirects  messages  sent  to 
Idevl console  to  that  xterm  window.  If  this  option  is  supported,  you  should  add  the  -C  option 
to  the  console  xterm  in  your  startup  file.  After  this  window  is  mapped  (displayed  on  the 
screen),  all  such  messages  are  displayed  there. 


Log  Files 

The  X server  creates  log  files  useful  in  fixing  a problem  that  might  occur.  These  files  are 
located  in  lusr/adm. 

You  should  make  provisions  to  trim  these  files  periodically.  As  with  all  log  files,  you  can  do 
this  automatically  with  an  entry  in  the  crontab  file. 


Changing  the  Color  Name  Database 

The  X Window  System  comes  with  a predefined  set  of  colors,  listed  in  the  file 
lusrlliblXlllrgb.txt.  You  can  use  these  color  names  to  specify  colors  either  on  the  command 
line  or  in  a resources  file.  If  you  have  the  X sources,  you  can  customize  the  color  name  data- 
base using  the  following  procedure. 

1.  Edit  the  rgb.txt  source  file,  which  is  located  in  the  mitlrgb  directory,  to  change  or  add 
colors.  The  format  of  a line  in  the  rgb.txt  file  is: 

red  green  blue  colorname 

The  red,  green,  and  blue  values  are  integers  in  the  range  0 to  255;  the  color  name  is  case 
insensitive,  but  must  not  include  any  special  symbols.  A typical  entry  in  the  rgb.txt  file 
is: 


127  255  212aquamarine 

See  Chapter  8,  Command  Line  Options , for  more  about  color  specifications. 
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2.  Run  the  rgb  program  using  the  makefile  also  located  in  the  mit/rgb  directory.  This  pro- 
gram converts  the  text  file  ( rgb.txt ) to  a UNIX  dbm(  1)  format  file  ( rgb.dir ),  which  is  used 
as  the  color  database.  Just  type: 

% make 

3.  Then  install  the  new  rgb.dir  file  in  lusr/lib/Xll  by  typing: 

% make  install 


If  the  color  name  database  gets  corrupted  in  some  way  (e.g.,  written  to  accidentally),  the 
server  may  not  be  able  to  find  any  colors  with  which  to  display.  On  a black  and  white  works- 
tation, you  may  get  error  messages  similar  to  the  following: 


X Toolkit 
X Toolkit 
X Toolkit 
X Toolkit 


Warning : 
Warning : 
Warning : 
Warning : 


Cannot  allocate  colormap  entry 
Cannot  allocate  colormap  entry 
Cannot  allocate  colormap  entry 
Cannot  allocate  colormap  entry 


for  White 
for  Black 
for  white 
for  black 


If  you  get  errors  of  this  sort,  perform  steps  2 and  3 in  the  procedure  described  above.  This 
will  overwrite  the  corrupted  rgb.dir  file. 
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The  uwm  Window  Manager 


This  appendix  describes  uwm,  the  Release  3 standard  window  manager, 
which  has  been  moved  to  the  user-contributed  distribution  in  Release  4.  It 
covers  both  the  basics  of  using  uwm  and  how  to  customize  it. 

In  This  Chapter: 


Starting  the  Window  Manager 556 

The  WindowOps  Menu 556 

Creating  New  Terminal  Windows 558 

Refreshing  the  Screen  559 

Redrawing  a Window 560 

Moving  Windows  and  Icons  560 

Resizing  Windows  561 

Shuffling  the  Window  Stack:  Raise,  Lower,  Circlip,  CircDown 563 

Raising  Windows  (bringing  in  front  of  others)  564 

Lowering  Windows  (sending  behind  others)  564 

Circulating  Windows  565 

Displaying  Windows  as  Icons 565 

Changing  Keyboard  Focus 567 

Freezing  and  UnFreezing  the  Server 568 

Restarting  the  Window  Manager 568 

Removing  a Window 569 

Exiting  the  Window  Manager 569 

Button  Control  of  Window  Manager  Functions 569 

Using  uwm  to  Place  Other  Clients 570 

The  Preferences  Menu  571 

Customizing  uwm  572 

Setting  .uwmrc  Variables  575 

Button/Key  Bindings  576 

Function  Names  576 

Keys  576 
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Executing  System  Commands  from  a Menu  581 

Cut  Buffer  Strings  582 
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A Complete  Revamp  of  uwm  585 
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The  uwm  Window  Manager 


If  you  are  running  Release  3 of  X (or  an  earlier  release),  the  standard  window  manager  is 
uwm,  the  universal  window  manager,  uwm  allows  you  to  perform  all  of  the  basic  window 
manipulation  functions,  such  as: 

• Sizing  and  positioning  client  windows  on  the  screen  interactively. 

• Creating  additional  xterm  terminal  windows. 

• Refreshing  your  screen. 

• Moving  windows  around  the  screen. 

• Changing  the  size  of  windows. 

• Lowering  windows  (sending  them  to  the  back  of  others). 

• Raising  windows  (bringing  them  to  the  front  of  others). 

• Converting  windows  to  icons  and  icons  to  windows. 

• Removing  windows. 

The  uwm  window  manipulation  functions  can  be  invoked  in  three  ways: 

• Using  the  WindowOps  menu. 

• By  combinations  of  keyboard  keys  and  pointer  buttons. 

• Automatically,  when  a client  is  started  (to  allow  you  to  size  and  place  the  client  window 
on  the  screen). 

The  window  manager  also  has  a second  menu,  the  Preferences  menu,  that  allows  you  to  set 
various  keyboard  and  pointer  preferences. 

Be  aware  also  that  you  can  customize  nearly  every  feature  of  uwm  by  modifying  a window 
manager  startup  file  called  .uwmrc,  kept  in  your  home  directory.  You  can  change  the  key- 
stroke and  pointer  button  combinations  used  to  invoke  window  manager  functions,  modify 
the  default  uwm  menus,  create  new  menus,  etc. 
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The  first  half  of  this  appendix  discusses  the  default  window  manipulation  functions  provided 
by  uwm.  The  second  half  discusses  how  to  customize  the  window  manager  to  suit  your 
needs.  First,  however,  let’s  take  a look  at  starting  uwm. 


Starting  the  Window  Manager 

You  start  uwm  from  the  command  line  by  typing: 

% uwm  & 

in  an  xterm  window.  If  xdm  (the  display  manager)  is  starting  X on  your  system,  the  uwm 
window  manager  is  probably  started  automatically  when  you  log  on.  (See  the  discussions  of 
xdm  in  Chapter  2,  Getting  Started , and  Appendix  A,  System  Management.)  When  uwm  is 
started,  nothing  visible  will  happen,  but  your  terminal  will  beep  once  to  indicate  that  uwm  is 
running  on  the  current  screen. 

Note  also  that  you  can  run  xterm  or  other  X clients  without  running  a window  manager,  uwm 
allows  you  to  size  and  place  client  windows  on  the  screen,  but  you  can  also  use  command 
line  options  to  do  this.  However,  there  is  no  way  to  change  the  size  or  location  of  windows 
on  the  screen  without  a window  manager. 


The  WindowOps  Menu 

The  uwm  WindowOps  menu  gives  you  access  to  many  of  the  most  frequently  used  window 
manipulation  functions.  In  the  standard  version  of  uwm  shipped  by  MIT,  you  bring  up  this 
menu  by  moving  the  pointer  to  the  root  window  and  holding  down  the  middle  pointer  button. 
The  WindowOps  menu  and  the  menu  pointer  appear  as  shown  in  Figure  B-l. 

Note  that  the  last  two  items,  KillWindow  and  Exit,  appear  on  the  menu  as  of  Release  3.  If  you 
are  running  Release  2,  your  menu  will  not  include  these  items.  (However,  the  items  that 
appear  on  both  Release  2 and  Release  3 menus  are  identical  in  functionality;  our  discussions 
of  these  common  menu  items  apply  to  either  release.) 

Another  Release  3 feature  is  that  the  “hand”  pointer  is  used  to  indicate  the  window  to  be 
acted  upon  (resized,  refreshed,  etc.).  In  Release  2,  this  function  was  performed  by  the  “target 
circle”  pointer.  The  figures  in  this  appendix  depict  Release  3 pointers,  but  the  Release  2 and 
3 pointers  function  in  the  same  way. 
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Figure  B-1.  WindowOps  menu 


The  following  pages  explain  the  functions  of  the  uwm  WindowOps  menu.  Remember  that  all 
of  the  window  manager  functions  are  customizable.  Items  can  be  added  to  or  deleted  from 
this  menu  (and  the  Preferences  menu)  by  modifying  the  .uwmrc  window  manager  startup  file, 
as  described  in  the  section  “Customizing  uwm”  later  in  this  appendix.  This  appendix 
describes  the  window  manager  as  it  is  shipped  with  the  standard  release  of  the  X Window 
System  from  the  MIT  X Consortium. 

To  bring  up  the  WindowOps  menu,  move  the  pointer  to  the  root  window  and  hold  down  the 
middle  button  on  the  pointer.  To  select  a menu  item,  continue  to  hold  down  the  middle  but- 
ton and  move  the  pointer  to  the  desired  menu  item.  A horizontal  band,  or  highlighting  bar , 
follows  the  pointer.  When  you’ve  highlighted  the  desired  menu  item,  release  the  button.  The 
selected  function  will  be  executed.  Note  that  you  must  keep  the  pointer  within  the  menu  as 
you  drag  down  to  make  a choice,  or  the  menu  will  disappear  and  you’ll  have  to  start  over. 

Some  of  the  functions  on  the  menus  can  be  invoked  simply  by  pressing  a combination  of 
pointer  buttons  and  keyboard  keys.  We  discuss  these  “keyboard  shortcuts”  as  appropriate 
when  discussing  each  menu  function,  and  summarize  them  in  Table  B-1  later  in  this  appen- 
dix. These  shortcuts  all  make  use  of  the  “Mela”  modifier  key.  See  Chapter  1 1 , Setup  Clients , 
for  a discussion  of  how  to  determine  which  key  on  your  keyboard  serves  as  the  Meta  key. 
(For  the  Sun-3  keyboard,  for  example,  Meta  is  either  of  the  keys  labeled  “Left”  or  “Right.”) 
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Creating  New  Terminal  Windows 


You  can  create  new  xterm  terminal  windows  from  the  WindowOps  menu.  To  create  a termi- 
nal window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  New  Window  with  the  menu  pointer  and  release  the  pointer  button.  An  upper-left 
comer  cursor  appears  on  your  screen.  This  comer  cursor  tracks  pointer  movement.  You 
now  have  three  options: 

• Making  a Default-Size  Window.  Move  the  comer  cursor  to  the  position  desired  for 
the  upper-left  comer  of  the  window  and  click  the  left  pointer  button.  A default-size 
(80  x 24)  window  appears  on  your  screen  as  shown  in  Figure  B-2. 


Figure  B-2.  A default-size  xterm  window 


• Making  a Custom-Size  Window.  Move  the  comer  cursor  to  the  desired  position  for 
the  upper-left  comer  of  the  new  window.  Press  and  hold  down  the  middle  pointer 
button.  Notice  that  the  upper-left  comer  cursor  is  now  fixed  at  that  position  and  that  a 
lower-right  comer  cursor  appears. 

While  holding  down  the  middle  button,  move  the  comer  cursor  to  the  desired  position 
for  the  lower-right  comer  of  the  window.  The  window  size,  as  you  change  it,  appears 
in  the  upper-left  comer  of  your  screen.  Release  the  button.  A window  of  the  width 
and  height  you  specified  with  the  pointer  appears.  See  Figure  B-3. 
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Figure  B-3.  A custom-size  xterm  window 


• Making  a Maximum-Height  Window.  Move  the  comer  to  the  desired  position  and 
click  the  right  button.  A default- width  by  maximum-height  (to  the  bottom  of  the 
screen)  window  appears.  See  Figure  B-4. 


Refreshing  the  Screen 


Refreshing  your  screen  means  redrawing  its  contents.  This  is  useful  if  system  messages  from 
outside  the  X window  system  appear  on  the  screen,  overlaying  its  contents.  To  refresh  your 
screen: 


1 . Bring  up  the  WindowOps  menu. 

2.  Select  RefreshScreen  with  the  menu  pointer.  The  screen  redraws  itself.  You  can  use  the 
xrefresh  client  to  achieve  the  same  effect.  Simply  type  xrefresh  at  the  prompt  in  any 
xterm  window. 
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Figure  B-4.  A maximum-height  xterm  window 

Redrawing  a Window 

The  Redraw  menu  item  redraws  (or  refreshes)  an  individual  window.  To  redraw  a window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Redraw  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  to  the  window  you  want  to  redraw. 

4.  Click  the  left  or  middle  button  to  redraw  the  window. 


Moving  Windows  and  Icons 


The  Move  menu  item  moves  a window  or  icon  to  a new  location.  When  you  use  this  func- 
tion, an  outline,  not  the  entire  window  or  icon,  tracks  the  pointer  movement  to  the  new  loca- 
tion. See  Figure  B-5.  To  move  a window: 

1 . Bring  up  the  WindowOps  menu. 

2.  Select  Move  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 
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3.  Move  the  hand  pointer  to  the  desired  window  or  icon.  Hold  down  the  middle  button.  The 
pointer  changes  to  the  cross  pointer  and  a window  outline  appears.  This  outline  tracks 
the  pointer  movement. 

4.  Move  the  cross  pointer  with  the  window  outline  to  the  desired  location  on  your  screen. 

5.  Release  the  middle  button.  The  window  will  move  to  the  new  location. 


Figure  B-5.  Moving  windows  or  icons 

You  can  also  move  a window  or  icon  simply  by  moving  the  pointer  to  the  window  or  icon 
you  want  to  move,  then  pressing  the  right  pointer  button  while  holding  down  the  Meta  key. 
The  pointer  at  first  changes  to  a small  image  of  an  icon.  You  can  now  let  go  of  the  Meta  key. 
Then,  as  you  drag  the  pointer  while  holding  down  the  button,  the  pointer  changes  to  a cross, 
while  the  window  or  icon  changes  to  outline  form.  Drag  the  outline  to  the  new  location,  and 
let  go  of  the  right  button.  The  window  will  be  redrawn  in  the  new  location. 


Resizing  Windows 

The  Resize  menu  item  resizes  an  existing  window.  See  Figure  B-6.  To  resize  a window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Resize  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 
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3.  Move  the  hand  pointer  to  the  window  you  want  to  resize.  Place  it  near  the  border  you 
want  to  move.  The  opposite  border  remains  in  its  current  position. 

4.  Hold  down  the  middle  button.  The  pointer  changes  to  the  cross  pointer. 

5.  Move  the  window’s  border  to  obtain  the  desired  window  size.  As  you  resize  the  window, 
a digital  readout  appears  opposite  the  pointer  showing  the  window  size  in  pixels.  (For  the 
xterm  client,  size  is  in  characters  and  lines.)  Release  the  middle  button. 


Figure  B-6.  Resizing  a window 

You  can  also  resize  a window  without  using  the  menu.  Move  the  pointer  so  that  it  is  within 
the  window  you  want  to  resize,  placing  the  pointer  near  the  window  border  you  want  to 
change.  With  one  hand,  press  and  hold  down  the  Meta  key  on  the  keyboard.  With  the  other 
hand,  press  and  hold  down  the  middle  pointer  button.  The  pointer  starts  as  an  icon  pointer, 
but  as  you  drag  the  pointer,  it  changes  to  a cross  and  a window  outline  appears.  Move  the 
pointer  to  resize  the  window.  When  the  window  is  the  proper  size,  release  the  middle  button 
and  the  Meta  key. 

Resizing  an  xterm  window  will  not  change  the  dimensions  of  the  text  currently  in  the  win- 
dow. (If  you  make  the  window  smaller,  for  instance,  some  of  the  text  may  be  obscured.) 
However,  if  the  operating  system  supports  terminal  resizing  capabilities  (for  example,  the 
SIGWINCH  signal  in  systems  derived  from  BSD  4.3),  xterm  will  use  these  facilities  to  notify 
programs  running  in  the  window  whenever  it  is  resized.  As  you  continue  to  work,  perhaps 
starting  an  editing  session,  the  program  will  use  the  entire  window.  If  you  resize  during  an 


562 


X Window  System  User’s  Guide 


editing  session,  the  text  editing  program  may  not  know  about  the  new  size,  and  may  operate 
incorrectly.  Simply  quitting  out  of  the  editor  and  starting  another  session  should  solve  this 
problem. 

If  your  resized  xterm  window  does  not  seem  to  know  its  new  size,  you  may  be  working  with 
an  operating  system  that  does  not  support  terminal  resizing  capabilities.  Refer  to  the  discus- 
sion of  the  resize  client  in  Chapter  4,  The  xterm  Terminal  Emulator , (and  to  the  resize  refer- 
ence page  in  Part  Three  of  this  guide)  for  alternative  solutions. 


Shuffling  the  Window  Stack:  Raise,  Lower,  Circlip,  CircDown 

Under  the  X Window  System,  windows  can  overlap  each  other.  When  windows  overlap,  one 
or  more  windows  may  be  fully  or  partially  hidden  behind  other  windows  (see  Figure  B-7). 
You  can  think  of  these  windows  as  being  stacked  on  top  of  each  other  much  the  way  papers 
are  stacked  on  a desk,  uwm  can  control  the  stacking  order  of  the  windows.  Stacking  func- 
tions include:  raising  a window  to  the  top  of  the  stack,  making  all  of  it  visible;  lowering  a 
window  to  the  bottom  of  the  stack  (possibly  obscuring  it  by  other  windows);  circulating  the 
bottom  window  to  the  top  and  lowering  every  other  window  one  level;  or  circulating  the  top 
window  to  the  bottom  and  raising  every  other  window  one  level. 


Figure  B-7.  One  xterm  window  overlapping  another 
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Raising  Windows  (bringing  In  front  of  others) 

The  Raise  menu  item  places  a window  at  the  top  of  a window  stack.  See  Figure  B-8.  To 
bring  a window  to  the  front: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Raise  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  to  the  desired  window. 

4.  Click  the  left  or  middle  button.  The  window  is  raised  to  the  top  of  the  stack. 


Figure  B-8.  Raising  a window 

Lowering  Windows  (sending  behind  others) 

The  Lower  menu  item  places  a window  at  the  bottom  of  a window  stack.  To  place  a window 
at  the  bottom: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Lower  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  to  the  appropriate  window. 

4.  Click  the  left  or  middle  button.  The  desired  window  is  placed  behind  all  windows  except 
the  root  window. 
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Circulating  Windows 


The  Circlip  and  CircDown  menu  items  circulate  the  windows  in  a stack.  Circlip  raises  the  bot- 
tom window  to  the  top  and  lowers  every  other  one  by  one  level.  CircDown  lowers  the  top 
window  to  the  bottom  and  raises  every  other  window  by  one  level.  Circlip  and  CircDown 
only  affect  overlapping  windows. 

To  circulate  the  windows  in  a stack: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Circlip  or  CircDown. 

Note  that  both  Circlip  and  CircDown  circulate  every  window  stack  if  there  is  more  than  one 
stack  of  windows  on  the  screen. 

Here’s  how  to  change  the  stacking  order  using  keyboard  shortcuts: 

• To  raise  a window,  move  the  pointer  so  that  the  cursor  is  within  the  window  you  want  to 
raise.  With  your  other  hand,  hold  down  the  Meta  key  on  the  keyboard.  Then  click  the 
right  pointer  button.  The  window  is  raised. 

• To  lower  a window,  move  the  pointer  so  that  the  cursor  is  within  the  window  you  want  to 
lower.  With  your  other  hand,  hold  down  the  Meta  key  on  the  keyboard.  Then  click  the 
left  pointer  button.  The  window  is  lowered. 

• To  circulate  all  windows,  you  can  use  any  of  the  above  key  and  pointer  button  combina- 
tions with  the  pointer  in  the  root  window.  However,  you  do  not  place  the  cursor  within 
any  particular  window  (e.g.,  leave  the  cursor  in  the  root  window).  The  windows  cycle 
through  the  stack,  raising  the  bottom  window  to  the  top  and  lowering  every  other  window 
one  level. 


Displaying  Windows  as  Icons 

If  you  want  to  make  more  space  available  on  your  screen,  you  can  convert  a window  into  an 
icon.  An  icon  is  a small  symbol  that  represents  the  window.  You  also  can  convert  the  icon 
back  into  a window. 

There  are  three  menu  items  on  the  default  WindowOps  menu  used  to  iconify  and  deiconify: 
Autolconify,  Lowerlconify,  and  Newlconify.  All  three  iconify  a window  or  deiconify  an  icon. 
In  addition,  Lowerlconify  and  Newlconify  interactively  move  the  icon  or  window  to  a new 
location.  See  Figure  B-9  and  Figure  B-10. 

To  convert  a window  to  an  icon  or  an  icon  to  a window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Newlconify  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  to  the  desired  window  or  icon. 
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Figure  B-9.  The  login  window  is  about  to  become  an  icon 

4.  Hold  down  the  left  button  and  move  the  pointer  to  the  desired  location.  The  window  or 
icon  tracks  the  pointer  to  the  new  location. 

5.  Release  the  left  button.  The  window  is  converted  to  an  icon  or  the  icon  to  a window  in 
the  new  location. 

While  the  pointer  rests  in  the  icon,  you  can  edit  the  icon  name  by  typing  in  the  appropriate 
name  or  characters.  Use  the  Delete  key  to  delete  unwanted  characters. 

Newlconify  can  also  be  used  to  display  an  icon  as  its  original  window.  Follow  the  same  pro- 
cedure as  to  iconify  a window,  but  start  with  an  icon,  and  turn  it  into  a window. 

To  iconify  or  deiconify  a window  using  keyboard  shortcuts,  move  the  pointer  so  that  the  cur- 
sor is  within  the  window  you  want  to  iconify.  With  one  hand,  press  and  hold  down  the  Meta 
key  on  the  keyboard.  With  the  other  hand,  press  and  hold  the  left  pointer  button  and  drag  the 
window.  The  window  converts  to  an  icon-sized  outline.  Drag  the  outline  to  the  desired  posi- 
tion, and  then  release  the  pointer  button  and  the  Meta  key.  The  full  icon  appears  in  the  speci- 
fied position. 

To  bring  back  the  window  (deiconify  it),  move  the  pointer  so  that  the  cursor  is  within  the 
icon.  Then  hold  down  the  Meta  key  and  click  the  middle  pointer  button.  The  window 
appears  back  in  its  original  position.  Or  hold  down  the  Meta  key  and  use  the  left  pointer  but- 
ton while  dragging  the  window  outline  to  a new  location,  just  as  you  did  to  iconify  the 
window  in  the  first  place. 
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Figure  B-10.  The  login  window  is  about  to  be  deiconified 


Changing  Keyboard  Focus 

Normally,  keyboard  input  goes  to  whichever  window  the  pointer  is  currently  in.  The  Focus 
option  causes  keyboard  input  to  go  only  to  a selected  window  (the  focus  window)  regardless 
of  the  position  of  the  pointer. 

Focusing  can  be  useful  if  you  are  working  in  one  window  for  an  extended  period  of  time,  and 
want  to  move  the  pointer  out  of  the  way.  It  also  prevents  the  annoying  situation  in  which  you 
inadvertently  knock  the  pointer  out  of  the  window  while  typing.  (This  can  be  very  important 
for  touch  typists  who  look  infrequently  at  the  screen  while  typing!) 

To  choose  a focus  window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Focus  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  to  the  window  you  want  to  choose  as  the  focus  window. 

4.  Click  the  middle  button  to  choose  the  window. 
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The  focus  window  becomes  highlighted  with  a dark  border. 

In  order  to  take  the  focus  away  from  the  selected  window  (and  reactivate  “pointer  focus”), 
you  must  give  the  focus  back  to  the  root  window.  To  do  this,  select  Focus  again,  and  click 
anywhere  on  the  root  window.  The  keyboard  focus  will  once  again  follow  the  pointer  into 
any  window. 


Freezing  and  UnFreezing  the  Server 


The  X server  normally  responds  to  requests  from  clients  in  a first-come  first-served  order. 
There  are  times  when  you  want  one  client  (such  as  the  window  manager)  to  get  priority  treat- 
ment. For  example,  if  there  are  many  active  X clients,  or  if  you  are  running  X across  a slow 
network,  you  may  find  that  uwm  responds  sluggishly  while  performing  tasks  such  as  moving 
or  resizing  a window.  If  you  select  Freeze,  the  window  manager  “grabs  the  server,”  so  that 
no  other  clients  have  access.  All  events  and  requests  to  display  to  the  screen  by  other  clients 
are  queued,  or  “saved  up,”  and  will  be  performed  when  the  server  is  unfrozen. 

To  freeze  the  server: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Freeze  with  the  menu  pointer. 

Since  only  the  window  manager  has  access  to  the  server,  window  manager  operations  will  go 
much  more  quickly.  When  you  are  finished  moving  or  resizing  windows  (or  whatever  it  was 
you  wanted  the  window  manager  to  do  more  quickly),  select  Unfreeze  to  resume  normal 
operation. 


Restarting  the  Window  Manager 

The  Restart  menu  item  restarts  the  window  manager.  This  may  occasionally  become  neces- 
sary if  the  window  manager  functions  improperly.  To  stop  and  restart  the  window  manager 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Restart  with  the  menu  pointer. 

You  may  also  want  to  restart  the  window  manager  if  you  edit  your  .uwmrc  configuration  file 
to  change  the  functionality  of  uwm.  For  more  information,  see  the  section  “Customizing 
uwm”  later  in  this  appendix. 

Note  that  when  the  window  manager  is  stopped,  all  icons  revert  to  windows.  This  happens 
because  the  window  manager  is  what  allows  windows  to  be  iconified.  When  the  window 
manager  is  restarted,  you  can  iconify  the  windows  again. 
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Removing  a Window 


The  KillWindow  menu  item  terminates  a client  window.  Like  other  methods  of  ‘killing’  a pro- 
gram (such  as  the  xkill  client),  the  KillWindow  menu  item  can  adversely  affect  underlying 
processes. 

Most  windows  can  be  removed  in  ways  that  do  not  harm  relevant  processes.  For  example, 
you  can  generally  remove  an  xterm  window  by  typing  the  same  command  you  use  to  log  off 
the  system.  KillWindow  is  intended  to  be  used  primarily  after  more  conventional  methods  to 
remove  a window  have  failed. 

To  remove  a stubborn  window: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  KillWindow  with  the  menu  pointer.  The  pointer  changes  to  the  hand  pointer. 

3.  Move  the  hand  pointer  into  the  window  you  want  to  terminate. 

4.  Click  any  pointer  button. 

The  window  is  removed. 

Refer  to  the  section  on  xkill  in  Chapter  7,  Other  Clients , for  a more  complete  discussion  of 
the  hazards  of  killing  a client  and  a summary  of  alternatives. 

Exiting  the  Window  Manager 

The  Exit  menu  item  stops  the  window  manager.  You  may  want  to  stop  uwm  in  order  to  start 
another  window  manager.  To  stop  uwm: 

1.  Bring  up  the  WindowOps  menu. 

2.  Select  Exit  with  the  menu  pointer. 

The  window  manager  is  stopped.  All  icons  revert  to  windows. 


Button  Control  of  Window  Manager  Functions 

Table  B-l  summarizes  the  keyboard  shortcuts  for  window  management  functions.  The  first 
column  lists  the  desired  function;  the  second,  the  required  location  for  the  pointer;  and  the 
third,  the  button-key  combination.  In  this  column,  “click”  means  to  press  and  immediately 
release  the  specified  pointer  button;  “down”  means  to  press  and  hold  the  pointer  button,  and 
“drag”  means  to  move  the  pointer  while  holding  down  the  pointer  button.  In  all  cases,  you 
can  let  go  of  the  keyboard  key  as  soon  as  you  have  pressed  the  appropriate  pointer  button. 

Note  that  these  key  “bindings”  can  be  changed  in  your  .uwmrc  file  as  described  later  in  this 
appendix.  The  combinations  described  in  Table  B-l  work  for  the  default. uwmrc  file. 
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Table  B-1.  Keyboard  Shortcuts  for  Window  Manager  Functions 


Function 

Pointer  Location 

Keyboard  Shortcut 

Move 

Window  or  icon 

Meta  key,  right  pointer  button  down  and  drag. 

Resize 

Window 

Meta  key,  middle  pointer  button  down  and  drag. 

Raise 

Window  or  icon 

Meta  key,  right  pointer  button  click  . 

Lower 

Window  or  icon 

Meta  key,  left  pointer  button  click. 

Circulate  up 

Root 

Meta  key,  right  pointer  button  click. 

Circulate  down 

Root 

Meta  key,  left  pointer  button  click. 

Circulate  down 

Anywhere 

Meta-Shift  key  combination,  left  pointer  button 
click. 

Iconify  and  move 

Window  or  icon 

Meta  key,  left  pointer  button  down  and  drag. 

Deiconify  and  move 

Icon 

Meta  key,  middle  pointer  button  click. 

WindowOps  menu 

Root 

Meta  key,  middle  pointer  button  down. 

WindowOps  menu 

Anywhere 

Meta-Shift  key  combination,  middle  pointer 
button  down. 

Preferences  menu 

Anywhere 

Meta-Shift  key  combination,  middle  pointer 
button  down  (must  display  WindowOps  with 
Meta-Shift  middle  down  and  slip  off). 

Using  uwm  to  Place  Other  Clients 

As  described  in  Chapter  2,  Getting  Started,  you  can  start  another  client  simply  by  typing  its 
name  at  the  command  line  prompt  in  an  xterm  window.  Some  clients  have  a default  size 
and/or  location.  A preferred  size  and  location  can  also  be  specified  in  your  ^resources  file, 
as  described  in  Chapter  9,  Setting  Resources. 

When  you  start  a client,  you  can  also  use  the  -geometry  command  line  option  described  in 
Chapter  8,  Command  Line  Options,  to  size  and  locate  the  window,  overriding  any  defaults 
that  the  client  has. 

If  none  of  these  geometry  specifications  has  been  provided,  uwm  steps  in  and  requires  you  to 
interactively  size  and  locate  the  windows.  You  have  already  seen  the  process  of  interactively 
sizing  and  positioning  a window  in  Chapter  2,  when  we  discussed  how  to  start  a second  xterm 
or  an  xclock  window. 

First,  the  pointer  turns  into  a comer  shape  and  the  name  of  the  client  appears  in  the  upper-left 
comer  of  the  screen  followed  by  the  digital  size  readout  0x0. 

To  place  the  default-size  client,  move  the  pointer  to  the  desired  upper-left  comer  position  for 
the  new  client.  Click  the  left  pointer  button. 

To  both  size  and  place  the  client,  move  the  pointer  to  the  desired  upper-left  comer  position; 
press  and  hold  down  the  middle  pointer  button.  The  pointer  changes  to  a lower-right  comer 
shape.  Move  the  pointer  to  the  desired  window  size.  Release  the  pointer  button. 
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The  Preferences  Menu 


The  Preferences  menu  is  generally  included  in  the  version  of  uwm  provided  with  most  sys- 
tems. The  Preferences  menu  lists  options  for  setting  bell  volume,  keyclick  volume,  whether 
or  not  the  Caps  Lock  key  works,  and  the  pointer  tracking  speed.*  See  Figure  B-l  1 . 


% uwm& 
% xterm& 

% 


Preferences  = 

Bell  Loud 

Bell  Normal 

! % xclock& 

Bell  Off 

|% 

Click  Loud 

Click  Soft 

Click  Off 

Lock  On 

. i 

Lock  Off 

Mouse  Fast 

•V'--  ' ' "!  ’ :: 

j Mouse  Normal 

| Mouse  Slow 

Figure  B-11.  Preferences  menu 


Without  customizing  the  window  manager,  the  only  way  to  display  the  Preferences  menu  is 
to  first  display  the  WindowOps  menu  by  an  alternative  method.  Instead  of  placing  the  pointer 
on  the  root  window  and  holding  down  the  middle  pointer  button,  place  the  pointer  anywhere 
on  the  screen,  hold  down  both  the  Shift  and  Meta  keys,  and  press  the  middle  pointer  button. 
(See  Chapter  11,  Setup  Clients,  for  a discussion  of  how  to  determine  which  key  on  your  key- 
board serves  as  the  Meta  key.)  The  WindowOps  menu  is  displayed. 

You  can  let  go  of  the  Shift  and  Meta  keys,  but  keep  holding  down  the  middle  pointer  button. 
Then  drag  the  pointer  off  the  right  or  left  side  of  the  WindowOps  menu  and  the  Preferences 
menu  will  be  displayed. 


*The  pointer  tracking  speed  controls  how  much  the  pointer  moves  on  the  screen  when  you  move  the  pointer.  Experi- 
ment with  each  setting  and  see  which  you  are  most  comfortable  with. 
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Menus  displayed  in  this  way  are  called  slip  off  menus  and  are  discussed  in  greater  detail  in 
the  section  “Customizing  uwm.”  This  section  also  describes  how  to  set  up  the  window  man- 
ager to  display  the  Preferences  menu  more  easily. 

To  make  selections  on  the  Preferences  menu,  bring  up  the  menu  and  select  a setting  with  the 
menu  pointer.  There  is  no  visible  change  to  the  menu,  but  the  new  setting  is  made.  Note  that 
another  button  or  combination  might  be  used  to  display  the  Prefences  menu  at  your  site.  If 
you  cannot  access  the  Preferences  menu,  this  menu  is  included  in  the  sample  .uwmrc  file  at 
the  end  of  this  appendix. 


Customizing  uwm 

As  we’ve  seen,  uwm  allows  you  to  manipulate  windows  in  a variety  of  ways.  In  addition, 
you  can  modify  every  function  of  the  uwm  window  manager.  The  function  itself  will  remain 
the  same  (for  example,  you  will  still  move  a window  by  holding  down  a key  and  pointer  but- 
ton simultaneously  and  dragging  the  pointer),  but  the  keys  and/or  menu  items  used  to  invoke 
the  function  may  be  completely  different. 

The  flexibility  of  uwm  allows  you  to  redesign  the  WindowOps  and  Preferences  menus  by 
reordering,  adding  and  removing  items,  and  changing  key/button  combinations,  and  to  create 
entirely  new  menus.  The  operation  of  the  window  manager,  as  distributed,  is  controlled  by  a 
text  file  called  default. uwmrc,  which  is  generally  installed  in  the  directory  /usr/lib/Xll/uwm. 
You  can  customize  uwm  by  editing  a copy  of  this  file,  called  .uwmrc,  in  your  home  directory. 
By  customizing  this  file,  you  can: 

• Define  your  own  uwm  menus. 

• Bind  functions  to  keyboard  key/pointer  button  combinations. 

• Issue  command  strings  to  the  shell. 

The  .uwmrc  file  has  three  parts: 

• A variables  section,  which  contains  various  settings,  such  as  the  font  with  which  menus 
should  be  displayed,  the  volume  of  the  keyboard  bell,  and  so  on. 

• A key  bindings  section,  which  defines  the  keys,  pointer  buttons,  and  key  and  pointer  but- 
ton combinations  that  will  be  used  to  invoke  each  window  manager  function  (including 
the  display  of  menus). 

• A menus  section,  which  defines  the  contents  of  the  menus. 

As  users  gain  experience  with  the  window  manager,  each  can  create  a file  called  .uwmrc  in 
his  or  her  home  directory.  This  file  can  extend  default. uwmrc,  resetting  variables,  changing  a 
key  binding  or  adding  a menu  item — or  it  can  replace  it  completely,  changing  the  way  the 
window  manager  operates.  As  one  of  its  creators  remarked,  this  flexibility  makes  uwm  “the 
bane  of  trade  show  demonstrators  and  the  joy  of  experienced  users.”* 

*Joel  Gancarz,  “UWM:  A User  Interface  for  X Windows,"  in  USENIX  Conference  Proceedings,  Summer  1986, 
p.  431. 
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Rather  than  abstractly  explaining  the  syntax  of  these  various  sections  in  a .uwmrc  file,  let’s 
plunge  right  in,  by  looking  at  the  default. uwmrc  file  from  the  MIT  XI 1 distribution.  This  is 
shown  in  Example  B-l.  (Note  that  if  you  are  using  a commercial  version  of  X,  this  file  may 
be  significantly  different.  However,  in  that  case,  you  most  likely  have  a user’s  guide  specific 
to  your  system — perhaps  even  a customized  version  of  this  one!) 

Example  B-1.  The  default.uwmrc  file  from  the  MIT distributbn 

# Copyright  (c)  1987  by  the  Massachusetts  Institute  of  Technology. 

# 

# This  is  a startup  file  for  uwm  that  produces  an  xwm  lookalike, 

# but  adds  two  useful  menus.  It  is  patterned  on  the  public 

# distribution  .. /lib/X/uwm/ jg . uwmrc  file  by  Jim  Gettys . 

# 

resetbindings 

re set variables 

resetmenus 

noautoselect 

delta=5 

freeze 

grid 

zap 

pushabsolute 

push=l 

hiconpad=5 

viconpad=5 

hmenupad=3 

vmenupad=0 

iconfont=f ixed 

menufont=f ixed 

resizefont=f ixed 

volume=0 


# FUNCTION 

KEYS  CONTEXT 

MOUSE  BUTTON 

ACTIONS 

f . newiconify= 

meta 

window | icon : 

delta  left 

f . raise= 

meta 

window | icon : 

delta  left 

f . lower= 

meta 

window | icon : 

left  up 

f . raise= 

meta 

window : 

middle  down 

f . resize= 

meta 

window : 

delta  middle 

f . iconify= 

meta 

icon : 

middle  up 

f . raise= 

meta 

window | icon : 

right  down 

f .move= 

meta 

window | icon : 

delta  right 

f . circledown= 

meta 

root : 

left  down 

f . circleup= 

meta 

root : 

right  down 

f . circledown= 

m | s 

: 

left  down 

f . menu= 

root : 

middle  down 

: "WindowOps" 

f .menu= 

m | s 

middle  down 

: "WindowOps" 

f .menu= 

m | s 

middle  down 

: "Preferences 

f . circleup^ 

m | s 

right  down 

f . iconif y= 

m | c 

window | icon : 

left  down 

f . newiconify= 

m 1 1 

window | icon : 

left  down 

f . raise= 

m 1 1 

window | icon : 

left  up 

f .pushright= 

m | 1 

window | icon : 

right  down 

f .pushleft= 

m | c 

window | icon : 

right  down 

f . pushup= 

m | 1 

window | icon : 

middle  down 

f . pushdown= 

m | c 

window | icon : 

middle  down 
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Example  B-1.  The  default,  uwmrc  file  from  the  MIT  distribution  (continued) 


f . raise= 

m 1 1 

f .pushright= 

m 1 1 

f .pushleft= 

m | c 

f . pushup= 

m | 1 

f . pushdown= 

m | c 

: window | icon : left  up 
: window | icon : right  down 
: window | icon : right  down 
: window | icon : middle  down 
: window | icon : middle  down 


menu  = "WindowOp 
New  Window:  ! " 
Ref reshScreen : f . 
Redraw:  f. 
Move : f . 
Resize:  f. 
Lower:  f. 
Raise:  f. 
CircUp:  f. 
CircDown:  f. 
Autolconify:  f. 
Lowerlconify : f. 
Newlconify:  f. 
Focus:  f. 
Freeze:  f. 
UnFreeze:  f. 
Restart:  f. 
" " : f . 
KillWindow:  f. 
" " : f . 
Exit:  f. 
) 


s"  { 

xtermS " 

refresh 

redraw 

move 

resize 

lower 

raise 

circleup 

circledown 

iconify 

newiconify 

newiconif y 

focus 

pause 

continue 

restart 

beep 

kill 

beep 

exit 


menu 

= "Preferences" 

{ 

Bell 

Loud : 

! "xset 

b 

7&  " 

Bell 

Normal : 

! "xset 

b 

3 & " 

Bell 

Off: 

! "xset 

b 

off&" 

Click 

Loud : 

! "xset 

c 

8 & " 

Click 

Soft : 

! "xset 

c 

on&  " 

Click 

Off: 

! "xset 

c 

offs" 

Lock 

On : 

! "xset 

led  on&" 

Lock 

Off: 

! "xset 

led  off& 

Mouse 

Fast : 

! "xset 

m 

4 2 & " 

Mouse 

Normal : 

! "xset 

m 

2 5 & " 

Mouse 

Slow : 

! "xset 

m 

1 IS" 

} 


If  you  wish  to  change  the  operation  of  the  window  manager,  you  shouldn’t  change  the 
default.uwmrc  file.  Instead,  copy  it  to  your  home  directory,  under  the  name  .uwmrc,  and 
make  changes  to  that  copy.  Or  else,  if  you  are  planning  only  small  changes,  you  can  create  a 
.uwmrc  file  from  scratch.  Settings  in  default.uwmrc  and  your  own  local  .uwmrc  file  are 
cumulative  (unless  you  explicitly  override  default.uwmrc  as  explained  in  the  next  section),  so 
all  you  need  to  enter  in  your  .uwmrc  are  values  you  wish  to  change. 
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Setting  .uwmrc  Variables 


The  first  section  of  the  file  sets  global  variables.  Some  variables  are  Boolean — that  is,  then- 
presence  or  absence  “toggles”  some  attribute  of  the  window  manager — while  others  have  the 
form: 


va ri able- value 

where  value  is  either  a number  or  a text  string. 

An  example  of  a Boolean  variable  is  autoselect,  which,  if  present,  causes  the  pointer  to 
automatically  appear  in  the  first  menu  item  whenever  a menu  is  invoked.  Note  however  that 
there  are  inconsistencies  in  the  way  uwm  specifies  Boolean  variables.  Some,  like  reset- 
variables,  take  effect  if  present;  they  must  be  deleted  from  the  file  or  commented  out  by 
placing  a sharp  sign  (#)  at  the  start  of  the  line  if  you  don’t  want  them  to  take  effect.  Others, 
such  as  normali  (which  makes  sure  that  icons  aren’t  placed  partially  offscreen  when 
created),  have  an  opposite  toggle  (nonormali),  which  must  be  used  if  you  want  the  oppo- 
site effect.  If  two  corresponding  on/off  toggles  are  both  mistakenly  placed  in  a file,  which- 
ever is  specified  later  in  the  file  takes  effect. 

An  example  of  a text  string  variable  is: 

menu f ont= fixed 

which  names  the  font  that  should  be  used  in  all  menus.  (See  Appendix  E,  Release  3 and  4 
Standard  Fonts,  for  lists  and  illustrations  of  fonts  in  the  standard  XI 1 distribution.) 

An  example  of  a numeric  variable  is: 

volume=4 

which  sets  the  volume  of  the  keyboard  bell  on  a scale  ranging  from  0 to  7. 

The  available  variables  are  described  in  detail  on  the  uwm  reference  page  in  Part  Three  of 
this  guide,  so  we  won’t  go  into  detail  on  each  of  them  here.  Three  variables  that  are  worthy 
of  note,  though,  are  resetvariables,  resetbindings,  and  resetmenus.  You 
may  recall  that  settings  in  your  local  .uwmrc  file  are  cumulative  with  those  in  the 
default. uwmrc  file.  That  is,  you  need  define  only  changed  or  added  variable  values,  function 
bindings  or  menus  if  you  are  happy  with  the  basic  operations  set  forth  in  default. uwmrc.  If, 
however,  you  want  to  start  with  a clean  slate,  you  should  use  one  or  more  of  the  three  reset 
variables  which  reset,  respectively,  the  three  sections  of  the  .uwmrc  file.  If  specified,  these 
variables  should  always  head  the  list  of  variables. 

One  additional  note  of  syntax  that  is  not  obvious  from  the  default.uwmrc  example  shown 
above:  variable  definitions  need  not  be  written  on  separate  lines;  instead,  they  can  be 
separated  by  a semicolon  and  space.  For  example: 

resetvariables;  resetbindings;  resetmenus 


The  uwm  Window  Manager 


575 


indow  Manager 


Button/Key  Bindings 


The  second  section  of  the  .uwmrc  file  specifies  which  combination  of  keys  and  buttons  (and 
in  which  context)  will  be  used  to  invoke  each  predefined  uwm  function.  Let’s  see  how  this 
works,  by  looking  at  the  first  two  lines  of  the  function  binding  section  of  default. uwmrc. 

# FUNCTION  KEYS  CONTEXT  MOUSE  BUTTON  ACTIONS 

f . newiconify=  meta  : window | icon : delta  left 

The  first  line  we’ve  shown  is  just  a comment  line,  which  labels  each  of  the  fields  in  the  line 
below.  The  first  field  is  separated  from  the  others  by  an  equals  sign;  subsequent  fields  are 
separated  by  colons.  In  default. uwmrc,  fields  are  separated  by  tabs  for  clarity,  making  the 
colons  (falsely)  appear  to  be  delimiters  only  for  the  context  field;  they  could  instead  follow 
each  other  without  intervening  whitespace. 

Let’s  talk  about  each  of  the  fields  in  turn. 


Function  Names 

The  first  field  in  a key  binding  contains  the  name  of  a function,  followed  by  an  equals  sign. 

uwm  has  a number  of  predefined  functions.  Each  of  these  functions  has  a name  beginning 
with  “f  . ”.  The  meaning  of  most  of  these  functions  should  be  fairly  obvious  to  you  from  the 
name,  if  not  from  your  experience  using  the  window  manager.  For  example,  f . resize  is 
used  to  resize  a window,  f .move  to  move  a window,  or  f . iconify  to  change  a window 
to  an  icon. 

Others  are  less  obvious.  The  function  shown  in  the  example,  f .newiconify,  is  used  to 
turn  a window  into  an  icon,  or  an  icon  into  a window,  and  then  to  move  it  to  a new  location. 
Notice  the  function  f . beep,  which  appears  coupled  with  a set  of  empty  quotes  rather  than  a 
menu  selection.  This  line  in  the  .uwmrc  creates  a blank  line  on  the  WindowOps  menu,  to  iso- 
late the  KillWindow  and  Exit  selections  from  the  others.  If  you  select  the  blank  line,  the  key- 
board beeps. 

Each  of  the  functions  is  described  in  detail  on  the  reference  page  for  uwm  in  Part  Three  of 
this  guide. 


Keys 

The  second  field  lists  keys,  if  any,  which  must  be  held  down  while  invoking  the  specified 
function,  uwm  recognizes  a small  number  of  keys  (discussed  more  fully  in  Chapter  11 , Setup 
Clients ),  the  most  common  of  which  are  shift,  control,  lock  and  meta.  These  names  must  be 
entered  in  the  .uwmrc  file  in  lower  case,  and  can  be  abbreviated  s,  c,  1,  and  m. 

If  two  keys  must  be  held  down  at  once,  the  names  should  be  separated  by  a vertical  bar  ( I ). 
For  example,  c | s would  mean  that  the  Control  and  Shift  keys  should  be  pressed  simulta- 
neously. It  is  not  permissible  to  bind  a function  to  three  keys  at  once.  If  the  field  is  left 
blank,  no  key  needs  to  be  pressed  while  invoking  the  function. 
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Control,  Shift  and  Lock  should  be  familiar  to  most  users.  But  what  is  a “Meta”  key?  There 
isn’t  a key  by  that  name  on  many  keyboards — instead,  Meta  is  a user-definable  Control  key 
that  can  be  mapped  to  an  actual  key  on  the  physical  keyboard  using  the  xmodmap  client  as 
described  in  Chapter  11.  Most  implementations  of  X will  include  a mapped  Meta  key.  Type 
xmodmap  without  any  arguments  to  display  the  map.  The  default. uwmrc  specifies  the  Meta 
key  in  many  keyboard  bindings.  On  workstations  without  a special  key  corresponding  to 
Meta,  you  will  have  to  use  xmodmap  to  find  out  or  change  the  definition  of  Meta  to  some- 
thing reasonable. 

Meta  could  be  mapped  to  the  Control  key,  although  this  could  potentially  lead  to  conflicts 
with  applications  that  want  to  use  the  Control  key.  In  particular,  certain  functions  of  xedit 
will  operate  strangely  or  not  at  all  if  Meta  is  mapped  to  Control. 

If  you  want  to  map  the  Meta  key,  it  is  best  to  choose  a keyboard  key  that’s  within  easy  reach 
and  is  not  used  frequently  for  other  applications  (perhaps  an  Alt  or  Funct  key).  Left-  or  right- 
handedness  could  also  be  a factor  in  choosing  a Meta  key. 

The  developers  of  uwm  warn  against  binding  functions  to  the  Shift  key  alone,  since  they  say 
certain  applications  use  it  as  a Control  key.  If  you  use  it  in  uwm,  it  will  perform  both  func- 
tions simultaneously,  which  is  likely  to  be  confusing.  For  the  same  reason,  you  should  not 
bind  functions  to  buttons  without  modifier  keys,  except  in  the  context  of  the  root  window. 


Context 

The  third  field  defines  the  context — the  location  the  pointer  must  be  in  before  the  function 
can  be  invoked.  This  field  may  be  blank,  or  may  contain  one  or  more  of:  window,  icon,  or 
root.  Multiple  context  specifications  should  be  separated  by  vertical  bars. 

If  the  context  is  blank,  it  means  that  the  pointer  can  be  anywhere.  If  root  is  specified,  it 
means  that  the  pointer  must  be  in  the  root  (background)  window,  and  not  in  any  other  win- 
dow or  icon.  If  the  context  is  window  or  icon,  the  pointer  must  be  in  a window  or  icon  for 
the  function  to  be  invoked. 

The  context  field  makes  perfect  sense  if  you  consider  our  sample  function  binding: 

f . newiconify=  meta  : window | icon : delta  left 

f . newiconif  y turns  a window  into  an  icon,  or  an  icon  into  a window,  and  then  moves  it 
to  a new  location.  The  pointer  must  be  in  a window  or  an  icon  for  the  function  to  be  used. 


Mouse  Buttons 

The  fourth  field  defines  the  state  of  the  pointer  buttons  used  to  invoke  the  function. 

uwm  is  designed  to  be  used  with  a three-button  pointer,  and  keeps  separate  track  of  when  the 
button  is  pressed  and  when  it  is  released.  It  can  also  tell  when  the  pointer  is  moved. 

Accordingly,  a button  specification  has  two  parts: 
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• The  name  of  a button:  left,  middle  or  right.  These  must  be  in  lower  case,  and  can  be 
abbreviated  1,  m and  r. 

• The  state  of  the  button:  down,  up  (just  released),  or  delta  (held  down  while  the  pointer  is 
moving).  The  distance  in  pixels  the  pointer  must  be  moved  in  order  to  trigger  the  delta 
state  is  set  by  the  delta  variable,  and  is  set  to  5 in  default .uwmrc . The  actual  transla- 
tion of  pixels  to  distance  will  vary  from  system  to  system,  and  you  will  probably  want  to 
experiment  to  find  a value  that  you  are  comfortable  with.  The  context  for  the  delta  state 
is  the  context  at  the  point  the  button  was  first  pressed,  not  its  position  at  the  time  it  has 
moved  a delta  number  of  pixels. 

The  button  name  and  state  can  be  specified  in  either  order. 

Going  back  to  our  sample  function  binding: 

f . newiconif y=  meta  : window | icon : delta  left 

you  can  now  understand  that  the  f .newiconif y function  is  invoked  by  moving  the 
pointer  to  either  a window  or  an  icon,  pressing  the  Meta  key  and  the  left  pointer  button,  and 
dragging  the  pointer  in  any  direction. 

All  of  the  other  function  definitions  should  be  equally  readable  to  you.  Go  back  for  a 
moment  and  review  the  bindings  shown  in  the  default. uwmrc  file  in  Example  B-l. 

You’ll  notice  that  it  is  possible  to  bind  the  same  function  to  more  than  one  set  of  keys,  but- 
tons and/or  contexts.  For  example,  the  WindowOps  menu  can  be  invoked  anywhere  by  press- 
ing the  Meta  and  Shift  keys  together  with  the  middle  button  on  the  pointer.  But  when  the 
pointer  is  in  the  root  window,  the  WindowOps  menu  can  be  invoked  by  pressing  only  the 
middle  button  on  the  pointer.  The  reason  for  this  becomes  obvious  if  you  realize  that  when 
the  pointer  is  on  a window  or  an  icon,  the  middle  pointer  button  alone  might  have  some  other 
meaning  to  the  application  running  in  that  window.  In  order  to  avoid  conflict  with  other 
applications,  uwm  uses  the  more  complex  key/button  combination.  But  when  the  pointer  is 
in  the  root  window,  there  is  no  possibility  of  conflict,  and  it  can  take  a more  forgiving 
approach. 


Action 

The  fifth  field,  labeled  “Action,”  is  typically  used  only  for  the  f . menu  function,  which 
allows  you  to  invoke  menus.  The  fifth  field  specifies  the  name  of  a menu,  whose  contents  are 
defined  in  the  third  section  of  the  .uwmrc  file.  If  the  menu  name  contains  quotes,  special 
characters,  parentheses,  tabs,  or  blanks,  it  must  be  enclosed  in  double  quotes.  For  consis- 
tency, you  may  want  to  always  quote  menu  names.  For  example: 

f.menu=  : root : middle  down:  "WindowOps" 

f.menu=  m|s  ::  middle  down:  "WindowOps" 

f.menu=  m|s  ::  middle  down:  "Preferences" 
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Defining  Menus 


The  third  section  of  a .uwmrc  file  contains  menu  definitions.  These  definitions  have  the  for- 
mat: 


menu  = menuname  { 
item  name  : action 


} 


The  menu  name  must  exactly  match  a name  specified  with  the  f . menu  function. 

Each  item  on  the  menu  is  given  a label  ( item_name ),  which  will  appear  on  the  menu.  This 
is  followed  by  a colon  and  the  action  to  be  performed.  The  action  may  be  one  of  uwm’s  func- 
tions, or  if  prefixed  by  a ! character,  it  can  be  a system  command  to  be  executed,  as  if  in  an 
x term  window.  As  shown  in  Example  B-2,  the  WindowOps  menu  defined  in  default.uwmrc 
shows  both  types  of  action. 


Example  B-2.  The  WindowOps  menu 

menu  = "WindowOps"  { 

New  Window:  !"xterm&" 

Ref reshScreen : f. refresh 
Redraw:  f. redraw 

Move:  f.move 

Resize:  f. resize 

Lower:  f. lower 

Raise  : f . raise 

CircUp:  f.circleup 

CircDown:  f.circledown 

Autolconify:  f.iconify 

Lowerlconify : f.newiconify 

Newlconify:  f.newiconify 

Focus:  f. focus 

Freeze:  f. pause 

UnFreeze:  f. continue 

Restart:  f. restart 

" " : f.beep 

KillWindow:  f.kill 

f .beep 


Exit : 

} 


f . exit 


New  Window  is  accomplished  by  running  another  instance  of  xterm.  The  other  functions  are 
accomplished  simply  by  invoking  one  of  uwm’s  predefined  functions. 

The  Preferences  menu  shown  in  Example  B-3  simply  invokes  xset  with  a number  of  different 
options: 
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Example  B-3.  The  Preferences  menu 


menu  = "Preferences 

* { 

Bell  Loud: 

! "xset 

b 

7&  " 

Bell  Normal: 

! "xset 

b 

3&  " 

Bell  Off: 

! "xset 

b 

off&" 

Click  Loud: 

! "xset 

c 

8 & " 

Click  Soft: 

! "xset 

c 

ons" 

Click  Off: 

! "xset 

c 

off&" 

Lock  On: 

! "xset 

led  ons" 

Lock  Off: 

! "xset 

led  off& 

Mouse  Fast: 

! "xset 

m 

4 2&" 

Mouse  Normal: 

! "xset 

m 

2 5&" 

Mouse  Slow: 

! "xset 

m 

1 1&" 

} 


Submenus 


Frankly,  we  consider  the  menus  defined  by  the  default. uwmrc  file  to  be  rather  awkward  and 
far  from  complete.  Among  other  things,  the  WindowOps  menu  has  too  many  infrequently- 
used  functions  mixed  right  in  with  those  you  need  all  the  time. 

For  the  moment,  let’s  assume  that  we  want  to  leave  the  variable  definitions  and  function  key 
bindings  alone,  but  want  to  redefine  the  menus.  We  might  create  a local  .uwmrc  file  that  con- 
tained a menu  definition  like  the  one  shown  in  Example  B-4. 


Example  B-4.  Window  operations  divided  into  two  menus 


resetmenus 

menu  = "WindowOps"  { 
Move : 

Resize : 

Raise : 

Lower : 

(De) Iconify: 

New  window: 

Refresh  screen: 

Restart  window  manager: 

II  II  . 

KillWindow : 

More  Window  Operations: 
} 


f . move 
f . resize 
f . raise 
f . lower 
f . iconify 
! "xterm  -sb&" 
f . refresh 
f . restart 
f . beep 
f .kill 
f . beep 

f .menu : "More  Window  Operations" 


menu  = "More  Window  Operations"  { 

(De) Iconify  and  move:  f.newiconify 

Circulate  windows  up:  f.circleup 

Circulate  windows  down:  f.circledown 

Focus  keyboard  on  window:  f. focus 

Freeze  server:  f. pause 

Unfreeze  server:  f. continue 

" f .beep 

Exit:  f.exit 

} 
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We’ve  consolidated  the  three  original  menu  items  to  iconify  and  deiconify  into  two,  called 
(De)lconify  and  (De)lconify  and  Move.  The  latter  corresponds  to  the  Newlconify  choice  on  the 
standard  uwm  menu. 

To  get  from  one  menu  to  another,  we  simply  define  f . menu  as  the  action  for  one  item  on  the 
menu.  No  key,  button  or  context  is  defined,  so  we  go  right  to  the  next  menu  when  selecting 
that  item. 


Slip  off  menus 


In  Example  B-4,  there  was  no  keyboard  binding  for  the  More  Window  Operations  menu.  That 
menu  could  only  be  invoked  by  selecting  it  from  the  WindowOps  menu.  Another  way  to 
divide  the  window  into  two  would  be  to  give  both  the  same  key/button/context  binding,  as 
shown  in  Example  B-5. 

Example  B-5.  Window  operations  as  two  pull-right  menus 
resetbindings 

# Note  that  if  you  resetbindings,  you  must  recreate  all  desired 

# operations.  If  you  are  doing  this  kind  of  thing,  you'd  best  copy 

# the  entire  default . uwmrc  to  your  home  .uwmrc  and  edit  it 


f . menu= 

: root : 

middle 

down 

: "WindowOps" 

f .menu= 

: root : 

middle 

down 

: "More  Window 

Operations 

f . menu= 

m | s 

: : 

middle 

down 

: "WindowOps" 

f . menu= 

m | s 

: : 

middle 

down 

: "More  Window 

Operations 

If  two  menus  have  the  same  context  and  buttons,  you  can  cause  the  second  (or  third,  if  more 
than  two  are  defined)  to  appear  simply  by  selecting  nothing  from  the  first,  and,  while  continu- 
ing to  hold  down  the  specified  pointer  button  (you  can  let  go  of  the  key),  sliding  the  pointer 
off  the  menu  to  the  right  or  left.  The  first  menu  will  be  replaced  by  the  second. 

Slip  off  menus  may  be  awkward  to  control.  If  the  labels  of  menu  items  are  short,  the  menu 
can  be  too  narrow,  and  hence  difficult  to  use:  you  spend  much  more  time  sliding  off  menus 
unintentionally  than  you  do  selecting  items.  You  can  either  train  yourself  to  make  pointer 
movements  exactly  perpendicular,  or  you  can  add  horizontal  menu  padding  as  suggested  in 
the  revamp  of  uwm  at  the  end  of  this  appendix. 


Executing  System  Commands  from  a Menu 

We  mentioned  above  that  it  is  possible  to  specify  a system  command  as  a menu  action  simply 
by  placing  an  exclamation  point  in  front  of  the  string  to  be  executed.  As  we  saw,  the  menus 
defined  in  default. uwmrc  use  this  mechanism  to  create  a new  xterm  window. 

It  is  easy  to  cook  up  a menu  that  contains  a miscellany  of  useful  commands,  as  shown  in 
Example  B-6. 
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Example  B-6.  A Useful  Commands  menu 

f.menu=  : root : middle  down  : "Useful  Commands" 

menu  = "Useful  Commands"  { 

Analog  clock: 

Digital  clock: 

Edit  File: 

Calculator : 

Mailbox : 

Display  keyboard  mappings: 

} 

As  you  can  quickly  see,  you  can  run  any  window-based  programs  directly,  but  you  need  to 
run  other  programs  using  xterm' s -e  option  (discussed  in  Chapter  4,  The  xterm  Terminal 
Emulator).  You  are  limited  only  by  your  imagination  in  what  commands  you  might  want  to 
put  on  a menu.  Each  command  runs  in  its  own  window,  but  that  isn’t  necessarily  the  case,  as 
we’ll  see  in  a moment. 


! "xclock  —geometry  162x162— 10+10&" 

! "xclock  -digital  -geometry  1 62x37-10  + 1 74 & 
! "xterm  -e  vi" 

! "xcalc  -geometry  126x230-180+10&" 

!"xbiff  -geometry  65x65-353+10&" 

! "xmodmapS " 


Cut  Buffer  Strings 

Another  useful  feature  of  uwm's  menus  is  that  you  can  define  the  action  for  a menu  item  to  be 
the  insertion  of  a string  into  the  server’s  cut  buffer.  As  discussed  in  Chapter  4,  The  xterm 
Terminal  Emulator , you  can  use  this  cut  buffer  to  cut  and  paste  text  between  certain  client 
windows.  (See  Chapter  4 for  a more  complete  discussion  of  cut  buffers.)  You  can  also  use 
the  cut  buffer  from  within  uwm  to  define  strings  that  will  be  placed  in  the  cut  buffer,  ready  for 
pasting  into  a window. 

This  feature  is  useful  for  specifying  command  strings  that  you  want  to  have  executed  in  an 
existing  xterm  window. 

A string  prefixed  with  a vertical  bar  will  be  loaded  into  the  cut  buffer  with  no  trailing  new- 
line.  This  means  that  you  can  paste  the  string  into  a window  and  keep  typing  to  add  to  the 
command  line. 

A string  prefixed  with  a caret  will  be  terminated  with  a newline,  which  means  that  if  it  is  a 
command,  and  you  paste  it  at  the  shell  prompt  in  an  xterm  window,  it  will  be  executed  imme- 
diately. 

For  example,  we  could  add  the  following  lines  to  our  “Useful  Commands”  menu,  as  shown  in 
Example  B-7. 
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Example  B-7.  Useful  commands  using  cut  buffer  strings 
menu  = "Useful  Commands"  { 


Check  disk  space:  *"df" 

Remote  login:  | "rlogin" 

} 

The  last  item  on  the  menu  uses  I instead  of  A,  so  that  when  the  string  is  pasted  into  an  xterm 
window,  you  can  type  in  the  name  of  the  system  to  connect  to.  (If  you  tended  to  connect  to  a 
number  of  different  systems  on  a regular  basis,  you  could  also  just  create  a submenu  with  the 
names  of  various  systems  as  menu  items,  and  execute  the  correct  command  to  log  in  to  each 
system  from  there.) 

Of  course,  cut  buffer  strings  are  not  just  useful  for  pasting  in  commands  at  the  shell  prompt. 
You  could  also  associate  editing  macros  or  frequently-used  text  with  menu  items  for  use  with 
a text  editor. 

Unfortunately,  as  of  Release  3,  there  is  a serious  limitation  to  pasting  strings  from  a uwm 
menu,  related  to  the  discussion  of  cut  buffers  versus  text  “selections”  in  Chapter  4.  The  win- 
dow manager  uses  a cut  buffer  only;  most  Release  3 clients,  notably  xterm , use  selections. 
With  the  default  keyboard  translations  (Chapter  9),  the  contents  of  a selection  are  pasted 
before  the  contents  of  a cut  buffer.  Thus,  if  you’ve  been  copying  and  pasting  text  from  an 
xterm  window,  the  PRIMARY  (default)  selection  probably  contains  text.  If  you  then  choose 
the  Check  disk  space  item  from  the  uwm  menu,  that  menu  item  is  stored  in  the  cut  buffer,  but 
does  not  replace  the  PRIMARY  selection.  Whrn  you  go  to  paste  Check  disk  space  into  an 
xterm  window,  you  get  the  text  from  the  PRIMARY  selection  instead  (previously  cut  from  an 
xterm  window). 

To  solve  this  problem,  you  can  use  the  xcutsel  client  to  copy  the  text  from  the  cut  buffer  into 
the  .se/ection.  In  an  xterm  window,  type: 

% xcutsel  & 

and  then  position  the  xcutsel  window  using  the  pointer.  When  you  are  having  trouble  pasting 
text  yanked  from  a window  manager  menu  because  of  a previous  text  selection,  click  on  the 
Copy  0 to  Primary  command  button  in  the  xcutsel  window.  This  command  copies  text  in  the 
cut  buffer  (specifically  CUT_BUFFER  “0”)  to  the  PRIMARY  selection.  You  should  then  be 
able  to  paste  the  text  yanked  from  the  uwm  menu  successfully. 

Note  that  if  the  PRIMARY  selection  is  currently  empty,  the  text  in  the  cut  buffer  will  be 
pasted  instead,  and  this  problem  will  not  occur.  For  more  information  on  the  xcutsel  client, 
see  Chapter  4,  The  xterm  Terminal  Emulator,  and  the  xcutsel  reference  page  in  Part  Three  of 
this  guide. 
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Color  Menus 


So  far,  we’ve  assumed  that  all  menus  are  black  and  white.  But  you  can  also  create  color 
menus.  You  can  even  assign  different  colors  to  the  menu  title,  the  highlighting  bar  (the  hori- 
zontal band  that  follows  the  pointer  within  the  menu  and  shows  which  item  is  selected)  and 
the  individual  selections  on  the  menu. 

Colors  are  added  to  menus  using  the  following  syntax: 

menu  = "menu  name"  (title_fg:title_bg:highlight_fg:  highlight_bg ) { 

" item  name”:  (item_fg:item_bg):  " action " 


} 

Up  to  four  different  colors  can  be  defined  for  the  overall  menu: 


title_fg 
ti tle_bg 
highligh  t_fg 

highl±ght_bg 


The  foreground  color  of  the  menu  title  (i.e.,  the  color  of  the  lettering). 
The  background  color  of  the  menu  title. 

The  foreground  color  of  the  highlighting  bar  (i.e.,  the  color  of  the 
lettering  within  the  bar). 

The  background  color  of  the  highlighting  bar. 


Two  colors  can  be  defined  for  each  menu  item: 


i t em_fg  The  foreground  color  of  the  item  (i.e.,  the  color  of  the  lettering), 

i t em_bg  The  background  color  of  the  item. 

Colors  can  be  specified  either  with  color  names  or  hex  strings,  as  described  in  Chapter  8, 
Command  Line  Options. 

Here  s a color  menu  that  works  well  on  a Sun-3  workstation.  Keep  in  mind  that  the  colors  in 
the  color  database  may  look  different  on  different  servers. 

menu  — WindowGps"  (darkslategrey : plum : darkslategrey : plum)  { 

(slateblue: lightblue) : f .move 
( slateblue : 1 ightblue ) :f. resize 
(slateblue : lightblue) :f. raise 
(slateblue : lightblue) :f. lower 
(slateblue : lightblue) :f.iconify 
(slateblue: 1 ightblue ) : ! "xterms " 
r ( s lateblue : lightblue ) :f. refresh 

Restart  window  manager:  (slateblue : lightblue) : f . restart 


move : 

Resize : 

Raise : 

Lower : 

(De) Iconify : 

New  window: 
Refresh  screen: 


The  total  number  of  colors  that  can  be  allocated  by  the  window  manager  for  its  own  use  is 
specified  by  the  maxcolors  variable.  If  you  try  to  use  more  than  maxco lor s colors,  the 
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additional  colors  will  default  to  the  colors  of  the  root  window.  This  can  also  happen  if  the 
server  runs  out  of  free  colormap  entries. 

Some  releases  of  uwm  include  a color  menu  bug.  If  all  menu  items  in  the  file  are  specified  in 
color,  all  menus  default  to  black  and  white.  One  quick  fix  is  to  leave  the  final  item  on  the 
final  menu  in  the  file  in  black  and  white.  More  recent  versions  of  uwm  have  corrected  the 
problem. 


A Complete  Revamp  of  uwm 

Using  the  various  techniques  described  in  this  appendix,  we’ve  modified  the  default. uwmrc 
file  to  create  an  interface  we  think  is  more  helpful  to  the  average  user. 

Our  modified  .uwmrc  file,  shown  in  Example  B-8,  sets  up  four  slip  off  menus,  each  with  a 
slightly  different  focus.  In  effect,  we’ve  split  the  original  WindowOps  menu  into  two,  called 
WindowOps  and  More  Window  Operations,  renaming  and  modifying  many  of  the  selections, 
adding  a few  of  our  own,  and  putting  the  less  frequently  used  ones  on  the  second  menu.  The 
third  menu  offers  some  Useful  Commands  to  place  other  clients,  including  x clock  and  xcalc, 
and  to  execute  system  commands,  such  as  df  and  rlogin.  The  final  menu  is  a slightly  modi- 
fied Preferences  menu,  which  sets  different  keyclick  volumes,  leds,  and  pointer  speeds  than 
the  default. 

You  can  test  our  .uwmrc  (following)  or  just  use  it  as  a touchstone  to  create  your  own. 

Example  B-8.  Modified  .uwmrc  file 

resetbindings;  resetvariables;  resetmenus 

noautoselect 

delta=5 

freeze 

grid 

zap 

pushabsolute 
push=l 
hiconpad=l 6 
viconpad=l 6 
hmenupad=22 
vmenupad=l 
iconf ont=fg-l 6 
menu font= fixed 
resize font=f ixed 
volume=0 


# FUNCTION 

KEYS 

CONTEXT 

MOUSE  BUTTON  ACTIONS 

f . new i coni fy= 

met  a 

: window | icon : 

delta  left 

f . rai se= 

met  a 

rwindow | icon: 

delta  left 

f . 1 owe  r = 

met  a 

: window | icon: 

left  up 

f . raise= 

met  a 

: wi ndow : 

middle  down 

f . resize= 

met  a 

: window : 

delta  middle 

f . iconi fy= 

met  a 

: icon : 

middle  up 

f . rai se= 

met  a 

: window | icon : 

right  down 

f . mo  ve  = 

met  a 

: wi ndow | i con : 

delta  right 

f . ci rcledown= 

m | s 

: : 

left  down 
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Example  B-8.  Modified  .uwmrc  file  (continued) 


f . circledown= 

met  a 

root : 

left  down 

f . circleup= 

met  a 

root : 

right  down 

f . menu= 

root : 

middle  down 

: "WindowOps" 

f . menu= 

root : 

middle  down 

: "More  Window  Operations 

f . menu= 

root : 

middle  down 

: "Useful  Commands" 

f . menu= 

root : 

middle  down 

: "Preferences" 

f . menu= 

m | s 

middle  down 

: "WindowOps" 

f . menu= 

m | s 

middle  down 

: "More  Window  Operations 

f . menu= 

m | s 

middle  down 

: "Useful  Commands" 

f . menu= 

m | s 

middle  down 

: "Preferences" 

f . circleup= 

m | s 

right  down 

f . iconify= 

m | c 

window | i con : 

left  down 

f. newiconi fy= 

m | 1 

window | icon : 

left  down 

f . rai se= 

m | 1 

window | icon : 

left  up 

f . pushright= 

m | 1 

window | icon : 

right  down 

f . pushleft= 

m | c 

window | icon : 

right  down 

f . pushup= 

m | 1 

window | icon : 

middle  down 

f . pushdown= 

m | c 

window | icon : 

middle  down 

menu  = "WindowOps"  { 

Move : 

Resize : 

Raise : 

Lower : 

(De) Iconify : 

New  window: 

Refresh  screen: 

Restart  window  manager: 

Kill  window: 

} 


f . move 
f . resize 
f . raise 
f . lower 
f . iconify 
! "xterm  -sb  & 
f . refresh 
f . restart 
f . beep 
f -kill 


menu  = "More  Window  Operations"  { 
Iconify  and  move: 

Circulate  windows  up: 

Circulate  windows  down: 

Focus  keyboard  on  window: 

Freeze  server: 

Unfreeze  server: 

Create  color  window: 

Exit : 

} 


f . newiconi fy 
f . circleup 
f . ci rcledown 
f . focus 
f . pause 
f . continue 

! "xterm  -d  unix:0.1  -fg  darkslategrey 
-bg  lightblue  -bd  plum  -bw  5&" 
f . beep 
f . exit 


menu  — "Useful  Commands"  { 

Analog  clock:  ! "xclock  -hd  darkslategrey  -hi  darkslategrey 

-fg  mediumorchid  -bg  lightblue  -bd  plum  -bw  5 
-geometry  1 62x1 62-10+1 0& " 

• "xclock  -digital  -fg  darkslategrey  -bg  lightblue 
-bd  plum  -bw  5 -geometry  162x37-10+174&" 

! "xcalc  -geometry  126x230-180+104" 

! xbiff  -bg  lightblue  -fg  lightslategrey  -bd  plum 
-bw  3 -geometry  65x65-353+104" 

Display  keyboard  mappings:  !"xmodmap4" 

Check  disk  space:  ""df" 

Remote  login:  | "rlogin" 


Digital  clock: 

Calculator : 
Mailbox : 
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Example  B-8.  Modified  .uwmrc  file  (continued) 


menu  = 

Bell 
Bell 
Bell 
Click 
Click  Soft: 
Click  Off: 
Lock  On: 

Lock  Off: 
Mouse  Fast: 
Mouse  Normal: 
Mouse  Slow: 


{ 

! "xset  b 7 & " 

! "xset  b 3«" 

! "xset  b of f & " 
! "xset  c 9& " 

! "xset  c 2& " 

! "xset  c off&" 
! "xset  led  1&" 
! "xset  -led  1& 
! "xset  m 4 5&" 
! "xset  m2  5&" 
! "xset  m 1 1 & " 


"Preferences 
Loud : 

Normal : 

Off: 

Loud: 
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The  OSF/Motif  Window  Manager 

This  appendix  describes  the  OSF/Motif m window  manager,  mwm,  one  of  the 
more  popular  window  managers  in  the  X market  today.  It  describes  both  the 
basics  of  using  mwm  and  how  to  customize  it. 

In  This  Chapter: 

Getting  Started  with  mwm 591 

Starting  mwm  592 

Selecting  the  Window  to  Receive  Input  592 

Manipulating  Windows  with  the  mwm  Window  Frame 594 
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Using  an  Icon  Box  626 
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Getting  Started  with  mwm 

The  Motif  window  manager  (mwm)  is  one  of  the  more  popular  window  managers  available  in 
the  X market.  Developed  by  Ellis  Cohen  of  the  Open  Software  Foundation,  mwm  is  the  win- 
dow manager  component  of  OSF/Motif,  OSF’s  graphical  user  interface  (GUI),  mwm  allows 
you  to  perform  all  of  the  standard  window  manipulation  functions.  You  can: 

• Create  additional  xterm  windows. 

• Change  the  size  of  windows. 

• Move  windows  around  the  screen. 

• Raise  windows  (move  them  to  the  front  of  others). 

• Lower  windows  (move  them  to  the  back  of  others). 

• Convert  windows  to  icons  and  icons  to  windows. 

• Refresh  your  screen. 

• Remove  windows. 

Like  twm,  the  Motif  window  manager  allows  you  to  invoke  window  manipulation  functions 
in  a variety  of  ways: 

• Using  the  window  “frame”  and  various  features  available  on  it:  the  Minimize  (iconify) 
button.  Maximize  button,  title  area,  Window  Menu,  etc. 

• Using  the  Root  Menu. 

• Using  keyboard  keys,  pointer  buttons,  and  key  and  button  combinations. 

mwm  attempts  to  create  a three-dimensional  appearance,  which  is  somewhat  more  aesthetic 
than  the  look  provided  by  many  other  window  managers.  You’ll  probably  notice  that  win- 
dow frames,  various  command  buttons,  icons,  etc.,  appear  to  be  raised  to  varying  heights 
above  screen  level.  This  illusion  is  created  by  subtle  shading  and  gives  many  display  fea- 
tures a “beveled”  look,  similar  to  the  beveled  style  of  some  mirrors. 
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This  appendix  is  intended  primarily  for  those  using  the  default  version  of  mwm,  Release  1.0. 
If  mwm  has  been  customized  at  your  site  or  you  are  running  a different  version,  the  principles 
should  be  basically  the  same,  but  the  window  manipulation  functions  may  be  invoked  in  dif- 
ferent ways.  From  time  to  time,  we’ll  mention  how  commands  or  functionality  might  vary, 
depending  on  your  version  of  mwm. 

If  you  have  never  used  a window  manager  before,  first  read  Chapter  1 , An  Introduction  to  the 
X Window  System,  for  a conceptual  overview  of  what  a window  manager  does. 

In  this  appendix,  we’ll  take  a look  at  the  standard  window  manipulation  functions  provided 
by  mwm  and  the  wide  variety  of  methods  for  invoking  them.  Then  we’ll  consider  how  to  cus- 
tomize various  features  of  mwm.  Perhaps  the  most  useful  customization  that  can  be  per- 
formed involves  selecting  a keyboard  focus  policy,  either  pointer  focus  or  click-to-type 
(referred  to  as  explicit)  focus.  (Keyboard  focus  is  described  in  Chapter  1 , An  Introduction  to 
the  X Window  System.)  By  default,  mwm  uses  explicit  (click-to-type)  focus. 

First,  however,  let’s  start  with  some  basics:  how  to  start  mwm\  and  how  to  select  the  window 
to  receive  input,  also  known  as  the  active  window.  Then  we’ll  take  a look  at  perhaps  the 
most  distinguishing  feature  of  mwm : the  frame  it  places  around  all  windows  on  the  display. 


Starting  mwm 

As  described  in  Chapter  2,  Getting  Started,  you  can  start  a window  manager  from  the  com- 
mand line  in  an  x term  window.  The  following  command  line  starts  mwm: 

% mwm  £ 

If  xdm  (the  display  manager)  or  another  session  manager  is  starting  X on  your  system,  mwm 
is  probably  started  automatically  when  you  log  on.  If  mwm  is  already  running,  all  windows 
will  be  surrounded  by  the  characteristic  window  frame,  pictured  in  Figure  C-l. 

If  mwm  is  not  running,  start  it  using  the  command  line  above.  While  mwm  is  starting  up,  the 
root  window  pointer  changes  to  an  hour  glass  that  appears  to  be  filling  up  with  sand.  When 
the  hour  glass  is  full,  all  windows  will  become  framed,  indicating  that  mwm  is  running. 


Selecting  the  Window  to  Receive  Input 


By  default,  you  select  the  window  to  receive  input  (the  active  window)  by  clicking  the  first 
Pointer  button  anywhere  within  the  window.  As  we’ve  said,  this  focus  policy  is  called 
click-to-type,  or  explicit.  Whether  mwm  is  started  automatically  or  you  started  it  by  typing  in 
an  xterm  window,  you  must  then  click  in  a window  in  order  to  enter  text. 

Once  you  focus  input  to  a window,  all  text  typed  appears  in  that  window,  regardless  of  where 
you  move  the  pointer.  In  order  to  type  in  another  window,  you  must  transfer  focus  to  that 
window  by  clicking  the  first  pointer  button  within  it  Later  in  this  appendix,  we’ll  describe 
how  to  make  the  keyboard  focus  follow  pointer  movement. 
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Figure  C-1.  mwm  is  running  on  the  display 

When  you  focus  input  on  a window,  the  window  frame  changes  color.  Depending  on  the  ver- 
sion of  mwm  you  are  running  and  the  color  resources  specified  for  your  system,  the  frame 
may  change  from  black  to  white,  from  grey  to  white,  etc.  In  any  case,  the  active  window’s 
frame  will  be  a different  color  than  the  frames  of  all  other  windows  on  the  display.  (In  some 
versions,  be  aware  that  the  black  window  frame  of  non-active  windows  obscures  the  titlebar 
text,  which  also  appears  in  black.  Only  the  title  of  the  active  window  is  visible  in  these 
cases.) 

Notice  that  if  you  are  working  with  a stack  of  windows  that  overlap,  selecting  a window  as 
the  active  window  automatically  raises  that  window  to  the  top  of  the  stack.  (As  we’ll  see 
when  we  look  at  customization,  this  behavior  is  controlled  by  an  mwm  resource  variable 
called  autoFocusRai.se,  which  is  true  by  default.) 
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Manipulating  Windows  with  the  mwm  Window  Frame 

Figure  C-2  shows  an  xlerm  window  “framed”  by  mwm.  The  window  frame  itself  and  several 
features  of  it  are  tools  that  allow  you  to  manipulate  the  window  using  the  pointer. 


Window  Menu 
button 


title  bar 


title  area 


Minimize  (iconify) 
button 


Figure  C-2.  An  xterm  window  running  with  the  OSF/Motif  window  manager 


The  following  sections  describe  the  features  of  the  mwm  window  frame  and  the  functions 
they  perform.  Later,  we’ll  take  a look  at  menu  items  and  keyboard  shortcuts  that  also  per- 
form these  functions. 

Be  aware  that  mwm  also  allows  you  to  manipulate  icons  using  simple  pointer  actions,  menu 
items,  and  keyboard  shortcuts.  An  icon  is  a small  symbol  that  (generally)  represents  a win- 
dow in  an  inactive  state.  (See  Chapter  1,  Introduction  to  the  X Window  System,  for  more 
information  about  icons.)  After  we  learn  the  various  window  manipulation  functions,  we’ll 
look  at  the  section  “Manipulating  Icons.” 


Moving  a Window:  The  Title  Area 

When  you  select  a window  as  the  focus  window,  the  name  of  the  application  is  displayed 
within  the  title  area.  The  title  area  allows  you  to  move  the  window,  using  the  following 
steps: 

1.  Place  the  pointer  within  the  title  area.  The  pointer  changes  to  the  arrow  cursor. 

2.  Press  and  hold  down  the  first  pointer  button. 

3.  Move  the  window  by  dragging  the  pointer.  Figure  C-3  shows  one  being  moved  in  this 
way.  When  you  begin  to  move  the  window,  the  pointer  changes  to  a cross  arrow  pointer 
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and  a window  outline  appears.  This  outline  tracks  the  pointer’s  movement.  In  the  center 
of  the  screen,  a small,  rectangular  box  also  appears,  displaying  the  x and  y coordinates  of 
the  window  as  you  move  it 

4.  Drag  the  cross  arrow  pointer  with  the  window  outline  to  the  desired  location  on  your 
screen. 

5.  Release  the  first  pointer  button.  The  window  will  move  to  the  selected  location. 


Figure  C-3.  Moving  a window  by  dragging  the  title  area 


The  title  area  is  the  largest  section  of  the  horizontal  bar  that  spans  the  top  of  the  window 
frame.  This  horizontal  bar  is  known  as  the  titlebar.  Notice  that  whenever  you  move  the 
pointer  into  the  titlebar,  the  pointer  changes  to  the  arrow  cursor. 

In  addition  to  the  title  area,  the  titlebar  features  three  command  buttons:  one  on  the  left  and 
two  on  the  right.  These  command  buttons  are  described  in  the  following  sections. 
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Minimizing  (Iconifying)  and  Maximizing  a Window 


The  two  command  buttons  on  the  right  side  of  the  titlebar  are  the  Minimize  and  Maximize 
buttons.  The  Minimize  command  button  converts  a window  to  an  icon.  As  mentioned  previ- 
ously, an  icon  is  a small  symbol  that  represents  a window  in  an  inactive  state. 

The  Maximize  command  button  can  be  used  to  enlarge  a window  to  the  size  of  the  root  win- 
dow, and  once  the  window  has  been  enlarged,  to  convert  it  back  to  its  original  size. 

The  Minimize  Button 

The  Minimize  command  button,  immediately  to  the  right  of  the  title  area,  is  identified  by  a 
tiny  square  in  its  center.  This  button  allows  you  to  convert  the  window  to  an  icon  (iconify  it), 
using  the  following  steps: 

1.  Place  the  pointer  within  the  Minimize  command  button.  The  pointer  simply  has  to  rest 
within  the  button’s  outer  border,  not  within  the  tiny  square  identifying  iL 

2.  Click  the  first  pointer  button.  The  window  is  iconified.  Figure  C-4  shows  a window  being 
converted  to  an  icon  in  this  way. 
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By  default,  icons  are  displayed  in  the  bottom  left  comer  of  the  root  window,  mwm  can  also 
be  set  up  to  place  icons  in  another  location,  to  allow  you  to  place  them  interactively  using  the 
pointer,  or  to  organize  icons  within  a window  known  as  an  icon  box.  Later  in  this  appendix, 
we’ll  discuss  the  specifications  necessary  to  set  up  an  icon  box. 

If  you’ve  used  other  window  managers,  you  may  notice  that  icon  symbols  generated  by  mwm 
are  larger  and  more  decorated  than  those  generated  by  many  other  window  mangers.  This  is 
one  of  the  aesthetic  advantages  of  mwm.  Figure  C-5  shows  an  example. 


Figure  C-5.  xterm  window  icon  under  mwm 


To  convert  the  icon  back  to  a window  (deiconify  it),  place  the  pointer  on  the  icon  and  double 
click,  using  the  first  pointer  button.  The  window  is  redisplayed  in  the  position  it  appeared 
before  it  was  iconfied.  (See  the  section  “Manipulating  Icons”  for  a summary  of  functions.) 

The  Maximize  Button 

To  the  right  of  the  Minimize  command  button  (in  the  upper  right  comer  of  the  window),  the 
Maximize  command  button  is  identified  by  a larger  square  in  its  center.  The  Maximize  but- 
ton allows  you  to  enlarge  the  window  to  the  size  of  the  root  window,  and  once  it  has  been 
enlarged,  to  convert  it  back  to  its  original  size. 

To  maximize  a window,  use  the  following  steps: 

1.  Place  the  pointer  within  the  Maximize  command  button.  The  pointer  simply  has  to  rest 
within  the  button’s  outer  border,  not  within  the  square  identifying  it. 

2.  Click  the  first  pointer  button.  The  window  is  maximized.  Figure  C-6  shows  how  it’s 
done. 
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Figure  C-6.  Maximizing  a window 


The  large  window  should  function  in  the  same  way  it  did  before  it  was  maximized.  Theoreti- 
cally, you  can  maximize  an  xterm  window  to  have  a single,  very  large  terminal  screen.  How- 
ever, be  aware  that  certain  programs  you  may  run  within  an  xterm , such  as  the  vi  text  editor, 
do  not  always  work  properly  within  a window  of  this  size  (even  if  you’ve  used  the  resize 
client,  as  described  in  Chapter  4,  The  xterm  Terminal  Emulator).  The  Maximize  function  is 
more  safely  used  with  an  application  that  displays  a graphic  image  or  performs  a simple  func- 
tion, such  as  xclock. 

Also,  some  client  programs  that  do  not  support  resizing,  such  as  the  Release  3 version  of 
xcalc,  cannot  be  maximized  correctly.  In  the  case  of  xcalc , the  frame  surrounding  the  calcu- 
lator application  is  maximized,  but  the  actual  calculator  remains  the  same  size. 

The  Maximize  button  is  a toggle.  To  convert  a maximized  window  back  to  its  original  size, 
click  on  the  Maximize  button  again  with  the  first  pointer  button. 


Raising  a Window 

Windows  often  overlap  on  the  screen.  You  can  raise  a window  that  is  obscured  by  other 
windows  to  the  top  of  the  stack  using  the  mwm  frame.  To  raise  a window: 
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1.  Place  the  pointer  on  any  part  of  the  window  frame,  except  the  command  buttons  (Mini- 
mize, Maximize,  and  the  button  in  the  upper  left  comer  of  the  titlebar,  which  as  we’ll  see, 
brings  up  the  Window  Menu). 

2.  Click  the  first  pointer  button.  The  window  is  raised  to  the  top  of  the  stack. 

When  you  are  using  explicit  (click-to-type)  focus  and  the  other  default  mwm  resources,  this 
action  also  selects  the  window  to  receive  input,  i.e.,  makes  the  window  the  active  window. 

Resizing  a Window 


One  of  the  most  distinctive  and  useful  features  of  the  mwm  window  frame  is  not  at  all  obvi- 
ous. The  entire  frame  (other  than  the  title  area  and  the  command  buttons)  is  designed  to 
allow  you  to  resize  the  window  using  the  pointer.  Notice  that  the  frame  is  divided  by  small 
lines  into  eight  sections:  four  long  borders  (two  horizontal  and  two  vertical)  and  four 
comers.  Figure  C-7  shows  these  sections  of  the  window  frame. 


— corner 


vertical  border 


horizontal  border 


Figure  C-7.  The  outer  frame  is  divided  into  four  long  borders  and  four  corners 


If  you  place  the  pointer  within  a window  and  then  move  it  into  one  of  the  long  horizontal  or 
vertical  borders,  you’ll  notice  the  pointer  changes  to  a new  shape:  an  arrow  (pointing  toward 
the  window  border),  with  a short  line  perpendicular  to  it.  This  short  line  represents  the  win- 
dow border.  Try  moving  the  pointer  in  this  fashion  in  one  of  the  windows  on  your  display  to 
get  a better  idea  of  what  the  pointer  looks  like.  If  you  move  the  pointer  from  within  a win- 
dow into  the  outer  border  at  one  of  the  comers,  the  pointer  will  become  an  arrow  pointing 
diagonally  at  a small  comer  symbol,  as  pictured  in  Figure  C-8.  Figure  C-9  shows  all  of  the 
possible  resize  pointers. 

Once  the  pointer  changes  to  one  of  these  shapes,  you  can  move  the  border  (or  comer)  of  the 
window.  Resizing  from  one  of  the  long  borders  only  allows  you  to  change  one  dimension  of 
the  window:  a horizontal  border  can  only  be  moved  up  or  down,  changing  the  height;  a verti- 
cal border  can  only  be  moved  left  or  right,  changing  the  width. 
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Figure  C-8.  Window  with  resizing  pointer 
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Resizing  from  a comer  offers  the  most  flexibility.  You  can  move  a comer  in  any  direction 
you  choose,  changing  both  dimensions  of  the  window  if  you  want.  For  example,  you  can 
drag  the  lower  right  comer  of  a window  down  and  to  the  right  to  enlarge  the  window  in  both 
dimensions. 

You  determine  the  size  and  shape  of  the  window  by  choosing  the  border  or  comer  you  want 
to  extend  (or  contract)  and  moving  it  the  desired  amount  using  the  following  steps: 

1.  Move  the  pointer  from  within  the  window  to  the  border  or  comer  you  want  to  move.  The 
pointer  changes  to  one  of  the  symbols  pictured  in  Figure  C-9. 

2.  Press  and  hold  down  the  first  pointer  button  and  drag  the  window  border  or  comer  in  the 
direction  you  want.  As  you  resize  the  window,  an  image  of  the  moving  border(s)  tracks 
the  pointer  movement.  Also,  in  the  center  of  the  display,  a small  rectangular  window 
shows  the  dimensions  of  the  window  as  they  change  (in  characters  and  lines  for  xterm 
windows,  in  pixels  for  most  other  clients). 

3.  Resize  the  window  as  desired. 

4.  Release  the  first  pointer  button.  The  window  is  redisplayed  in  the  new  shape.  (The  bor- 
der image  and  window  geometry  tracking  box  disappear.) 

Figure  C-10  shows  a window  being  “stretched”  from  the  lower  right  comer. 


Figure  C-10.  Dragging  the  corner  to  make  a window  larger 
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The  Window  Menu  Button:  Display  a Menu  or  Close  the  Window 


The  command  button  on  the  left  side  of  the  titlebar  is  used  to  bring  up  the  Window  Menu, 
which  provides  seven  items  that  manipulate  the  window  and  its  icon.  The  following  sections 
describe  how  to  bring  up  the  Window  Menu  and  invoke  its  various  functions. 

This  command  button  also  has  another  function.  Double-clicking  the  first  pointer  button  on 
the  Window  Menu  command  button  kills  the  client  program  and  closes  the  window.  Be 
aware  that,  like  other  methods  of  ‘killing’  a program  (such  as  the  xkill  client),  double- 
clicking on  the  Window  menu  item  can  adversely  affect  underlying  processes.  Refer  to  the 
section  on  xkill  in  Chapter  7,  Other  Clients , for  a more  complete  discussion  of  the  hazards  of 
killing  a client  and  a summary  of  alternatives. 

You  can  customize  mwm  so  that  double-clicking  performs  no  function  by  setting  a resource 
variable,  wMenuButtonClick2,  to  false.  See  the  sections  “Setting  mwm  Resources” 
and  “mwm-Specific  Appearance  and  Behavior  Resources”  later  in  this  appendix,  and  the 
mwm  reference  page  in  your  OSF/Motif  documentation  for  details. 


Manipulating  Windows  Using  the  Window  Menu 


The  command  button  on  the  left  side  of  the  titlebar  is  used  to  display  the  Window  Menu.  The 
Window  Menu  can  actually  be  displayed  from  a window  or  an  icon.  As  we’ll  see,  certain 
menu  functions  apply  only  to  one  or  the  other.  This  section  describes  using  the  Window 
Menu  to  manipulate  a window.  (The  section  “Manipulating  Icons,”  later  in  this  appendix, 
describes  the  use  of  Window  Menu  items,  pointer  commands,  and  other  shortcuts  on  icons.) 

Six  of  the  seven  items  on  the  Window  Menu  (all  but  Lower)  allow  you  to  perform  functions 
that  can  also  be  performed  by  simple  pointer  actions  on  the  mwm  window  frame.  All  of  the 
items  can  also  be  requested  using  keyboard  shortcuts,  known  as  accelerators , because  they 
facilitate  the  action. 

Since  manipulating  a window  using  the  frame  is  very  simple  and  accessible,  you  will  proba- 
bly not  use  the  Window  Menu  often.  You  may  want  to  use  the  menu  to  Lower  a window, 
since  this  function  cannot  be  performed  by  a simple  pointer  action  on  the  frame.  (If  you 
learn  the  keyboard  shortcuts  for  this  menu  item,  you  may  not  need  the  Window  Menu  to 
manipulate  windows  at  all.)  You  may  find  the  menu  more  helpful  in  manipulating  icons,  as 
described  later  in  this  chapter.  In  any  case,  learning  the  functions  of  the  Window  Menu  is 
helpful  in  orienting  yourself  within  the  Motif  environment. 

The  Window  Menu  can  be  displayed  either  from  a window  or  from  its  icon.  The  Window 
Menu  command  button  is  in  the  upper  left  comer  of  the  window  frame  and  is  identified  by  a 
narrow  rectangle  in  its  center.  You  can  display  the  Window  Menu  from  a window  by  moving 
the  pointer  to  the  command  button  and  either: 

• Clicking  the  first  pointer  button. 

• Pressing  and  holding  down  the  first  pointer  button. 
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(You  can  also  display  the  menu  using  keyboard  shortcuts  described  at  the  end  of  this  section.) 
The  menu  is  displayed.  If  you’ve  clicked  the  first  pointer  button  to  display  the  menu  (the  eas- 
ier method),  the  first  item  that  is  available  for  selection  is  highlighted  by  a box.  Figure  C-ll 
shows  the  default  Window  Menu,  which  has  been  displayed  by  clicking  the  first  pointer  but- 
ton in  the  menu  command  button. 


Figure  C-1 1.  The  Window  Menu 


Notice  that  the  first  item  available  for  selection  (indicated  by  the  surrounding  box)  is  Move. 
The  first  item  on  the  menu.  Restore,  is  used  to  change  an  icon  back  into  a window  or  a maxi- 
mized window  back  to  its  original  size;  therefore,  it  is  not  useful  at  this  time.  The  fact  that 
Restore  is  not  selectable  is  also  indicated  by  the  fact  that  it  appears  in  a lighter  typeface. 

Notice  also  that  one  letter  of  each  menu  item  is  underlined.  This  letter  represents  a unique 
abbreviation  for  the  menu  item,  called  a mnemonic,  and  is  useful  in  selecting  the  item. 

Once  the  menu  is  displayed,  you  can  select  an  item  in  the  following  ways: 

• If  you  displayed  the  menu  by  pressing  and  holding  down  the  first  pointer  button,  drag  the 
pointer  down  the  menu  to  the  desired  item  and  release  the  first  button. 

• If  you  displayed  the  menu  by  clicking  the  first  pointer  button,  either: 

— Move  the  pointer  onto  the  item  and  click  the  first  button. 

— Type  the  unique  abbreviation  (the  underlined  letter).  (Though  several  of  the  abbre- 
viations are  capital  letters,  you  should  type  the  lower-case  equivalent.) 
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The  following  sections  explain  how  each  of  the  Window  Menu  items  works. 

To  remove  the  menu  without  making  a selection,  move  the  pointer  off  of  the  menu  and 
release  or  click  the  first  pointer  button,  as  appropriate. 

Notice  also  that  a keyboard  shortcut  follows  each  command.  The  keyboard  shortcuts  allow 
you  to  perform  all  of  the  functions  without  having  to  display  the  menu.  All  of  the  keyboard 
shortcuts  for  the  menu  items  involve  the  Alt  key  and  a function  key.  (Alt  is  a logical  key- 
name that  may  be  associated  with  a physical  key  of  another  name.  If  you  cannot  locate  the 
Alt  key  on  your  keyboard,  see  Chapter  11,  Setup  Clients , for  a discussion  of  the  xmodmap 
client.) 

There  are  also  keyboard  shortcuts  to  display  the  Window  Menu.  Once  you  place  the  pointer 
anywhere  in  the  window,  either  of  the  following  key  combinations  will  cause  the  menu  to  be 
displayed:  Shift-Escape  or  Meta-space.  (Like  Alt,  Meta  is  a logical  keyname  recognized  by 
X programs.  There  is  no  key  marked  “meta”  on  the  keyboard.  Rather  another  key,  such  as 
the  Compose  Character  key  on  the  DECstation  3100  keyboard,  functions  as  Meta.  See  Chap- 
ter 1 1,  Setup  Clients , for  more  information  about  the  Meta  key.) 

In  the  following  sections,  we  assume  you  have  displayed  the  Window  Menu  by  clicking  the 
first  pointer  button  on  the  menu  command  button.  (If  you  display  the  menu  by  pressing  and 
holding  down  the  first  pointer  button,  instructions  to  click  a pointer  button  can  be  roughly 
translated  to  mean  release  the  button.) 

Changing  the  Window  Location:  Move 

To  move  a window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Move  item  by  clicking  on  it  with  the  first  pointer  button,  or  by  typing  the  letter 
m.  The  menu  disappears.  The  pointer  changes  to  the  cross  arrow  pointer  and  appears  in 
the  center  of  the  window. 

3.  Move  the  window  by  dragging  the  pointer.  When  you  begin  to  move  the  window,  a win- 
dow outline  appears.  This  outline  tracks  the  pointer’s  movement.  In  the  center  of  the 
screen,  a small  rectangular  box  also  appears,  displaying  the  x and  y coordinates  of  the 
window  as  you  move  it. 

4.  Drag  the  cross  arrow  pointer  with  the  window  outline  to  the  desired  location  on  your 
screen. 

5.  Click  the  first  pointer  button.  The  window  will  move  to  the  selected  location. 

To  cancel  the  Move  function,  keep  the  pointer  stationary  and  click  the  first  button. 

The  Move  function  can  also  be  invoked  using  the  keyboard  shortcut  Alt-F7. 
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Resizing  the  Window:  Size 

To  resize  a window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Size  item  by  clicking  on  it  with  the  first  pointer  button,  or  by  typing  the  letter 
s.  The  menu  disappears.  The  pointer  changes  to  the  cross  arrow  pointer  and  appears  in 
the  center  of  the  window. 

3.  Move  the  pointer  from  within  the  window  to  the  border  or  comer  you  want  to  move.  The 
pointer  changes  to  one  of  the  symbols  pictured  in  Figure  C-9. 

4.  Once  the  pointer  has  become  one  of  the  resize  pointers,  you  can  drag  the  window  border 
or  comer  in  the  direction  you  want.  As  you  resize  the  window,  an  image  of  the  moving 
border(s)  tracks  the  pointer  movement.  Also,  in  the  center  of  the  display,  a small  rectan- 
gular window  shows  the  dimensions  of  the  window  as  they  change  (in  characters  and 
lines  ioTxterm  windows,  in  pixels  for  most  other  clients). 

5.  Resize  the  window  as  desired. 

6.  Click  the  first  pointer  button.  The  window  is  redisplayed  in  the  new  shape.  (The  border 
image  and  window  geometry  tracking  box  disappear.) 

The  Size  function  can  also  be  invoked  using  the  keyboard  shortcut  Alt-F8. 

To  cancel  the  Size  function,  don’t  move  the  pointer  near  any  of  the  borders;  just  click  the  first 

pointer  button. 

Iconifying  the  Window:  Minimize 

To  iconify  a window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Minimize  item  by  clicking  on  it  with  the  first  pointer  button,  or  typing  the  letter 
n. 

3.  The  window  is  converted  to  an  icon. 

The  Minimize  function  can  also  be  invoked  using  the  keyboard  shortcut  AU-F9. 

The  easiest  way  to  convert  an  icon  back  to  a window  is  to  place  the  pointer  on  the  icon  and 

double  click  with  the  first  button. 
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Changing  to  the  Maximum  Size:  Maximize 

To  make  a window  as  large  as  the  root  window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Maximize  item  by  clicking  on  it  with  the  first  pointer  button,  or  typing  the  letter 
x. 

3.  The  window  is  enlarged  to  the  size  of  the  root  window. 

The  Maximize  function  can  also  be  invoked  using  the  keyboard  shortcut  Alt-FlO. 

Moving  a Window  to  the  Bottom  of  the  Stack:  Lower 

The  Lower  menu  item  allows  you  to  send  a window  to  the  bottom  of  the  window  stack.  This 
is  the  only  Window  Menu  function  that  cannot  be  performed  simply  by  clicking  the  pointer  on 
the  window  frame.  To  lower  a window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Lower  item  by  clicking  on  it  with  the  first  pointer  button,  or  typing  the  letter  1. 

3.  The  window  is  moved  behind  others  on  the  display  to  the  bottom  of  the  window  stack. 

Though  this  function  cannot  be  performed  by  clicking  the  pointer  on  the  frame,  it  can  be 
invoked  using  the  keyboard  shortcut  Alt-F3. 

Removing  a Window:  Close 

The  Close  menu  item  terminates  the  client  window  and  the  window  is  removed  from  the  dis- 
play. This  powerful  command  is  separated  from  the  other  menu  items  by  a horizontal  line  to 
prevent  you  from  inadvertently  closing  a window. 

Be  aware  that,  like  other  methods  of  ‘killing’  a program  (such  as  the  xkill  client),  the  Close 
menu  item  can  adversely  affect  underlying  processes.  Most  windows  can  be  removed  in 
ways  that  do  not  harm  relevant  processes.  For  example,  you  can  generally  remove  an  xterm 
window  by  typing  the  same  command  you  use  to  log  off  the  system.  Refer  to  the  section  on 
xkill  in  Chapter  7,  Other  Clients , for  a more  complete  discussion  of  the  hazards  of  killing  a 
client  and  a summary  of  alternatives. 

Like  xkill , Close  is  intended  to  be  used  primarily  after  more  conventional  methods  to  remove 
a window  have  failed. 

To  remove  a stubborn  window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Close  item  by  clicking  on  it  with  the  first  pointer  button,  or  typing  the  letter  c. 

3.  The  window  is  removed. 
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The  Close  function  can  also  be  invoked  using  the  keyboard  shortcut  Alt-F4. 

Restoring  a Maximized  Window  or  an  Icon:  Restore 

The  Restore  menu  item  allows  you  to  restore  an  icon  to  a window  or  a maximized  window  to 
its  original  size.  To  restore  a maximized  window: 

1.  Bring  up  the  Window  Menu. 

2.  Select  the  Restore  item  by  clicking  on  it  with  the  first  pointer  button,  or  by  typing  the 
letter  r. 

3.  The  window  is  restored  to  its  original  size. 

The  Restore  function  can  also  be  invoked  using  the  keyboard  shortcut  Alt-F5. 

Restore  can  also  be  used  to  convert  an  icon  back  to  a window,  as  described  in  the  section 
“Manipulating  Icons  Using  the  Window  Menu”  below. 


Manipulating  Icons 

In  addition  to  manipulating  windows,  mwm  provides  several  easy  methods  for  manipulating 
icons.  The  following  functions  can  be  invoked  using  simple  pointer  button  actions  on  an 
icon: 

Move  Hold  down  the  first  pointer  button  and  drag  the  icon  to  the  desired  posi- 

tion. Then  release  the  button. 

Raise  Click  on  the  obscured  icon  with  the  first  pointer  button.  The  icon  is 

raised  to  the  top  of  the  stack. 

Restore  (Deiconify)  To  convert  an  icon  back  to  a window,  double-click  on  the  icon  with  the 
first  pointer  button. 


Manipulating  Icons  Using  the  Window  Menu 

You  can  also  display  the  Window  Menu  from  an  icon  and  invoke  menu  items  that  affect  it.  To 
display  the  menu,  just  place  the  pointer  on  the  icon  and  click  the  first  button.  (You  can  also 
use  either  of  these  keyboard  shortcuts:  Shift-Escape  or  Meta-space.) 

The  Window  Menu  displayed  from  an  icon  is  virtually  identical  to  the  menu  displayed  from  a 
window;  it  contains  all  of  the  same  items,  but  only  five  of  the  seven  are  selectable.  (When 
displayed  from  a window,  six  of  the  seven  items  are  selectable.)  The  five  selectable  items 
are:  Restore,  Move,  Maximize,  Lower,  and  Close.  These  items  perform  manipulations  on  an 
icon  analogous  to  those  performed  on  a window  (see  “Manipulating  Windows  Using  the 
Window  Menu”  earlier  in  this  appendix). 
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Two  menu  items,  Size  and  Minimize,  appear  in  a lighter  typeface,  indicating  they  are  not 
available  for  selection.  Size  cannot  be  selected  because,  unlike  a window,  an  icon  cannot  be 
resized.  Obviously,  Minimize  cannot  be  used  to  iconify  an  icon. 

Table  C-l  summarizes  the  Window  Menu  functions  when  invoked  from  an  icon.  For  instruc- 
tions on  selecting  an  item  and  performing  the  various  functions,  read  “Manipulating  Win- 
dows Using  the  Window  Menu”  earlier  in  this  appendix.  Note  that  the  keyboard  shortcuts 
(accelerators)  for  the  commands  are  also  the  same  as  those  described  for  windows. 

Table  C-1.  Window  Menu  Actions  on  an  Icon 


Menu  Item 

Function 

Shortcut 

Restore 

Converts  the  icon  back  to  a window. 

AU+F5 

Move 

Moves  the  icon  on  the  display. 

Alt+F7 

Size 

Not  available  for  selection. 

n/a 

Minimize 

Not  available  for  selection. 

n/a 

Maximize 

Converts  an  icon  to  a window  the  size  of  the 
root  window. 

Alt+FlO 

Lower 

Sends  an  icon  to  the  bottom  of  the  win- 
dow/icon stack. 

AU+F3 

Close 

Exits  the  client,  removing  the  icon. 

AU+F4 

Later  in  this  appendix,  we’ll  discuss  using  mwm  resources  to  set  up  an  icon  box,  a window  for 
organizing  icons  on  the  display.  Using  an  icon  box  changes  the  way  you  work  with  the  Win- 
dow Menu  from  an  icon  and  introduces  another  menu  item,  Packlcons,  which  reorganizes 
icons  in  the  icon  box.  See  “Using  an  Icon  Box”  later  in  this  chapter  for  details. 


The  Root  Menu 


The  Root  Menu  is  mwm's  main  menu.  It  provides  commands  that  can  be  thought  of  as  affect- 
ing the  entire  display  and  is  analogous  to  the  Twm  menu  describe  in  Chapter  3.  To  display 
the  Root  Menu,  move  the  pointer  to  the  root  window  and  press  and  hold  down  the  first  pointer 
button.  The  default  Root  Menu  appears  in  Figure  C-12. 
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Figure  C-12.  The  mwm  Root  Menu 

When  you  display  the  Root  Menu,  the  pointer  changes  to  the  arrow  pointer.  As  you  can  see, 

the  default  Root  Menu  offers  only  five  items.  To  select  an  item,  use  the  following  steps: 

1.  As  you  continue  to  hold  down  the  first  pointer  button,  move  the  pointer  onto  the  the 
desired  item  name.  (If  you  accidentally  move  the  pointer  off  the  menu,  it  will  still  remain 
displayed,  as  long  as  you  continue  to  hold  the  first  button  down.)  As  you  move  the 
pointer  onto  an  item,  notice  that  a rectangular  box  is  displayed  around  the  item  to  high- 
light it 

2.  Once  the  pointer  is  positioned  on  the  item  you  want,  release  pointer  button  one.  The 
action  is  performed. 


The  functions  performed  by  the  default  Root  Menu  are  described  below. 

New  Window  By  default,  this  command  runs  an  xterm  window  on  the  display  speci- 

fied by  the  DISPLAY  environment  variable,  generally  the  local  display. 
When  you  create  a new  window  (by  using  the  menu  or  typing  the  com- 
mand in  an  xterm),  the  new  window  automatically  becomes  the  active 
window. 


Shuffle  Up  If  windows  and/or  icons  are  stacked  on  your  display,  this  command 

moves  the  bottom  window  or  icon  in  the  stack  to  the  top  (raises  it). 

Shuffle  Down  If  windows  and/or  icons  are  stacked  on  your  display,  this  command 

moves  the  top  window  or  icon  in  the  stack  to  the  bottom  (lowers  it). 
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Refresh 


This  command  is  used  to  refresh  the  display  screen,  that  is,  redraw  its 
contents.  Refresh  is  useful  if  system  messages  appear  on  the  screen, 
overlaying  its  contents.  (The  xrefresh  client  can  be  used  to  perform  the 
same  function.  Simply  type  xrefresh  on  an  xterm  command  line.) 

Restart . . . Stops  and  restarts  mwm.  This  is  useful  when  you’ve  edited  the  .mwmrc 

configuration  file,  which  specifies  certain  mwm  features,  and  want  to 
activate  the  changes.  Since  this  function  is  potentially  more  dangerous 
than  the  other  Root  Menu  options,  it  is  separated  from  the  other  options 
by  a horizontal  line. 

When  you  select  Restart,  a dialog  box  appears  in  the  center  of  the 
screen  with  command  buttons  asking  you  to  either  Restart  mwm  or  Can- 
cel the  request.  Click  on  the  appropriate  command  button  using  the  first 
pointer  button. 

If  you  select  Restart  mwm,  the  window  manager  process  is  stopped. 
The  screen  will  momentarily  go  blank.  The  new  mwm  process  will  be 
started  immediately.  While  the  new  mwm  process  is  starting,  an  hour- 
glass symbol  is  displayed  in  the  center  of  the  otherwise  blank  screen. 
The  hourglass  appears  to  be  filling  up  with  sand  until  the  window  man- 
ager is  running  and  the  windows  again  are  displayed  on  the  screen. 

Keep  in  mind  that  you  can  add,  change,  or  remove  menu  items  using  the  mwm  configuration 
file,  .mwmrc,  in  your  home  directory.  We’ll  discuss  customizing  the  Root  Menu  later  in  this 
appendix. 


Customizing  mwm 

The  Motif  window  manager  is  one  of  the  more  flexible  window  managers  available  in  the  X 
market  today.  As  we’ve  seen,  mwm  provides  a wide  variety  of  methods  for  manipulating 
windows.  In  addition,  virtually  every  feature  of  mwm  can  be  customized.  You  can  change 
the  appearance  of  window  frames,  icons,  and  menus,  the  functions  available  on  the  Root 
Menu  and  the  Window  Menu,  the  keyboard  focus  policy,  how  icons  are  arranged  on  the  dis- 
play, as  well  as  the  appearance  of  client  applications  running  under  OSF/Motif.  As  we’ll  see, 
you  can  also  create  additional  menus,  displayed  from  the  root  window,  to  perform  manipula- 
tions on  the  display  as  a whole. 

Customization  of  mwm  is  controlled  in  two  ways: 

• Through  a special  file,  called  .mwmrc,  in  your  home  directory. 

• Through  mwm  resources  you  can  enter  in  your  Xresources  file. 

The  default  operation  of  mwm  is  largely  controlled  by  a system-wide  file,  called  sys- 
tem.mwmrc,  which  establishes  the  contents  of  the  Root  Menu  and  Window  Menu,  how  menu 
functions  are  invoked,  and  what  key  and  button  combinations  can  be  used  to  manipulate  win- 
dows. To  modify  the  behavior  of  mwm , you  can  edit  a copy  of  this  file  in  your  home  direc- 
tory. The  version  of  this  file  in  your  home  directory  should  be  called  .mwmrc.  We’ll  take  a 
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look  at  the  system.mwmrc  and  ways  to  edit  your  own  .mwmrc  file  to  make  the  window  man- 
ager work  more  effectively  for  you. 

In  addition  to  the  flexibility  provided  by  the  .mwmrc  file,  mwm  provides  dozens  of  applica- 
tion resources  that  you  can  set!  It’s  neither  practical  or  necessary  to  discuss  all  of  those 
resources  here.  (You  could  spend  quite  a long  time  customizing  mwm,  if  you  had  the  time 
and  inclination.)  We’ll  just  consider  some  basic  categories  into  which  mwm  resources  can  be 
divided  and  also  look  at  some  of  the  more  useful  resources.  See  Chapter  9,  Setting 
Resources,  for  syntax  rules  and  information  about  loading  resources  into  the  server  so  that 
they  will  be  accessible  to  client  programs.  See  the  mwm  reference  page  in  your  OSF/Motif 
documentation  for  descriptions  of  all  available  resources. 

In  the  remainder  of  this  appendix,  we’re  going  to  demonstrate  the  basics  of  customizing 
mwm  and  suggest  what  we  think  are  helpful  modifications.  (This  is  still  quite  a lot  to  absorb.) 
To  illustrate,  we’ll  discuss  how  to  customize  the  following  features  of  mwm: 

• The  menus  and  how  menu  functions  are  invoked. 

• The  keyboard  focus  policy. 

• How  icons  are  organized  (namely,  how  to  set  up  a window  known  as  an  icon  box,  in 
which  icons  on  the  display  can  be  organized). 

Before  we  can  customize  the  mwm  menus  or  the  ways  in  which  their  functions  are  invoked, 
we  need  to  take  a closer  look  at  the  system.mwmrc  file.  First,  however,  let’s  consider  an 
important  topic:  how  to  make  the  window  manager  aware  of  customizations. 


Activating  Changes  to  the  Window  Manager 

Be  aware  that  if  you  edit  your  .mwmrc  or  X resources  file  to  change  the  way  mwm  works,  the 
changes  will  not  take  effect  automatically.  Whether  you  change  resource  settings,  edit  your 
.mwmrc  file,  or  both,  you  must  restart  mwm  for  the  changes  to  take  effect. 

If  you  edit  your  resources  file,  you  must  first  make  the  server  aware  of  the  new  resource  spec- 
ifications by  using  the  xrdb  client.  Generally,  you  will  enter  the  following  command  at  the 
prompt  in  an  xterm  window: 

% xrdb  -load  .Xrasourcas 

The  settings  in  the  current  version  of  your  Xresources  file  will  replace  the  resource  settings 
previously  stored  in  the  resource  database.  You  can  merely  append  new  settings  to  the  old 
ones  using  the  xrdb  -merge  option.  See  Chapter  9,  Setting  Resources,  for  more  informa- 
tion. 

Once  you’ve  loaded  the  new  resource  settings,  you  can  restart  mwm.  This  can  be  done  using 
the  Restart  item  of  the  Root  Menu,  as  described  earlier  in  this  appendix.  When  mwm  has 
been  restarted,  it  should  reflect  any  changes  made  to  the  .mwmrc  and  Xresources  files. 
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The  system.mwmrc  File 


The  following  example  shows  the  system.mwmrc  file  shipped  with  OSF/Motif  Release  1.0.  If 
you’ve  used  other  window  managers,  this  file  may  seem  a bit  more  complicated  than  other 
configuration  files,  but  the  complexity  is  deceptive. 

If  you  wish  to  change  the  operation  of  mwm,  you  shouldn’t  change  the  system.mwmrc  file. 
Instead,  copy  it  to  your  home  directory,  under  the  name  .mwmrc,  and  make  changes  to  that 
copy. 

Example  C-1.  The  system.mwmrc  file,  Release  1.0 

# 

# DEFAULT  mwm  RESOURCE  DESCRIPTION  FILE  (system.mwmrc) 

# 

# 

# menu  pane  descriptions 

# 


# Root  Menu  Description 
Menu  RootMenu 
{ 

"Root  Menu" 

No-label 
"New  Window" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 
no-label 
"Restart ..." 

) 

# Default  Window  Menu 

Menu  Def aultWindowMenu 

{ 

"Restore"  R 

"Move"  M 

"Size"  s 

"Minimize"  n 

"Maximize"  x 

"Lower"  L 

no-label 

"Close"  c 

} 


f. title 
f . separator 
f.exec  "xterm  & 
f . circleup 
f . circle_down 
f . refresh 
f . separator 
f . restart 


Description 
MwmWi ndowMenu 

Alt<Key>F5 
Alt<Key>F7 
Alt<Key>F8 
Alt  <Key>F  9 
Alt  <Key>Fl 0 
Alt<Key>F3 

Alt<Key>F4 


f . normalize 
f . move 
f . resize 
f .minimize 
f . maximize 
f . lower 
f . separator 
f -kill 


# 

# key  binding  descriptions 

# 

Keys  Def aultKeyBindings 

{ 

f . post_wmenu 
f . post_wmenu 
f . nextkey 
f.prevkey 


i>nirtcK.ey>E  scape 
Meta<Key>space 
Meta<Key>Tab 
Meta  Shi f t <Key>Tab 


icon | window 
icon | window 
root | icon | window 
root | icon | window 
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Example  C-1.  The  system. mwmrc  file,  Release  1.0  (continued) 


f . next  key 
f . prev_key 
f . set_behavior 
f.next_key  transient 
f . circledown 
f . circle  up 

} 

# 

# button  binding  descriptions 

# 


Meta<Key>Escape 

Meta  Shi ft<Key>Escape 

Meta  Ctrl  Shift<Key>exclam 

Meta<Key>F6 

Meta<Key>Down 

Meta<Key>Up 


root | icon | window 
root | icon | window 
root | icon | window 
window 

root | icon | window 
root | icon | window 


Buttons  Def aultButtonBindings 


<BtnlDown> 

<Btn2Down> 

<BtnlDown> 

Meta<BtnlDown> 

Meta<Btn2Down> 

Meta<Btn3Down> 


frame | icon 
frame | icon 
root 

window | icon 
window | icon 
window | icon 


) 


f . rai se 
f . post_wmenu 
f.menu  RootMenu 

f . lower 
f . resize 
f . move 


Buttons  ExplicitButtonBindings 

{ 

<BtnlDown>  frame | icon 

<Btn2Down>  frame | icon 

<Btn3Down>  frame | icon 

<BtnlDown>  root 

Meta<BtnlDown>  window | icon 

Meta<Btn2Down>  window] icon 

Meta<Btn3Down>  window | icon 

} 


f . rai se 
f . post_wmenu 
f . lower 

f.menu  RootMenu 

f . lower 
f . resize 
f . move 


Buttons  PointerButtonBindings 

{ 


<BtnlDown> 

<Btn2Down> 

<Btn3Down> 

<BtnlDown> 

If  (Mwm*passButtons  == 
Meta<BtnlDown> 

Else 

<BtnlDown> 

Meta<BtnlDown> 

Meta<Btn2Down> 

Meta<Btn3Down> 


frame | icon 
frame | icon 
frame | icon 
root 
False ) 
window | icon 

window 
window | icon 
window | icon 
window | icon 


END  OF  mwm  RESOURCE  DESCRIPTION  FILE 


f . raise 
f . post_wmenu 
f . lower 

f.menu  RootMenu 

f . raise 

f . raise 
f . lower 
f . resize 
f . move 


The  system.mwmrc  file  can  be  divided  into  three  sections: 

• Menu  specifications. 

• Key  bindings. 

• Button  bindings. 
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Comment  lines  are  introduced  by  the  number  sign  (#). 

The  menu  section  of  the  system.mwmrc  file  defines  the  contents  of  the  Root  Menu  and  the 
Window  Menu.  Menu  item  labels  are  paired  with  predefined  mwm  functions. 

A binding  is  a mapping  between  a user  action  (such  as  a keystroke)  and  a function,  in  this 
case  a window  manager  function.  The  key  bindings  section  specifies  keyboard  keys  that  can 
be  used  to  invoke  some  of  the  pre-defined  window  manager  functions.  The  button  bindings 
section  specifies  pointer  buttons  or  key/button  combinations  that  can  be  used  to  invoke  vari- 
ous functions. 

Each  section  of  the  system.mwmrc  file  matches  the  following  basic  template: 

Section  Type  Section_Title 
{ 

definitions 

) 

For  example,  the  basic  syntax  of  a menu  specification  is  as  follows: 

Menu  menuname  . . . 

{ 

menu  items  defined 
} 

Menu  is  the  Section_Type.  The  other  possible  section  types  are  Keys  and  Buttons. 
The  Section_Title  is  somewhat  arbitrary.  In  this  case,  it  corresponds  to  the  title  of  a 
menu.  In  the  key  and  button  sections,  it  is  simply  a title  assigned  to  a group  of  bindings. 

However,  the  Section  Title  can  be  very  significant.  As  we’ll  see,  a section  title  can  be 
used  as  the  value  of  a resource  variable  in  your  Xresources  file.  Menu  titles  are  often  refer- 
enced elsewhere  in  the  .mwmrc  file.  The  menu_name  is  generally  paired  with  a pointer  but- 
ton action  (in  the  button  bindings  section  of  the  .mwmrc  file)  to  allow  you  to  use  a particular 
button  to  display  the  menu. 

The  syntax  of  the  actual  menu  items,  key  bindings,  and  button  bindings  requires  further 
explanation.  But  first,  let’s  take  a look  at  some  of  the  predefined  window  manager  functions. 

mwm  Functions 

mwm  has  a number  of  predefined  functions.  Each  of  these  functions  has  a name  beginning 
with  “f Several  functions  appear  in  the  system.mwmrc  file,  paired  with  the  method  by 
which  the  function  can  be  invoked:  by  menu  item,  pointer  button  action,  keystroke(s),  or  key 
and  pointer  button  combinations. 

The  meaning  of  most  of  these  functions  should  be  fairly  obvious  to  you  from  the  name,  if  not 
from  your  experience  using  the  window  manager.  For  example,  f . resize  is  used  to  resize 
a window,  f . move  to  move  a window,  or  f . minimize  to  change  a window  to  an  icon. 

Others  are  less  obvious.  The  function  f . post_wmenu  is  used  to  display  (or  post)  the  Win- 
dow Menu.  Notice  the  function  f.  separator,  which  appears  in  the  menu  definition 
coupled  with  the  instruction  no -label  rather  than  with  a menu  item.  This  line  in  the 
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.mwmrc  creates  a divider  line  on  a menu.  For  example,  such  a divider  line  is  used  to  isolate 
the  Restart . . . item  from  the  other  items  on  the  Root  Menu. 

As  we’ll  see,  the  function  f . menu  is  used  to  associate  a menu  with  the  key  or  button  bind- 
ing that  is  used  to  display  it  The  f . menu  function  takes  a required  argument:  the  menu 
name.  This  function  can  also  be  used  to  define  a submenu. 

Each  of  the  functions  is  described  in  detail  on  the  reference  page  for  mwm  in  your  OSF/Motif 
documentation. 

Menu  Specifications 


The  first  section  of  the  system.mwmrc  file  contains  specifications  for  the  Root  Menu  and  Win- 
dow Menu.  As  we’ve  said,  the  basic  syntax  of  a menu  specification  is  as  follows: 

Menu  menu_name  . . . 

{ 

menu  items  defined 
) 


Menu  items  are  defined  in  slightly  different  ways  for  the  Root  Menu  and  the  Window  Menu. 
The  following  text  in  the  system.mwmrc  file  creates  the  Root  Menu: 


# Root  Menu  Description 
Menu  RootMenu 


{ 

"Root  Menu" 
No-label 
"New  Window" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 
no-label 
"Restart ..." 

} 


f .title 
f . separator 
f.exec  "xterm  & 
f . circle_up 
f . circledown 
f . ref resh 
f . separator 
f . restart 


The  syntax  for  defining  Root  Menu  items  is  very  simple.  Each  item  is  defined  by  a line  of  this 
format: 


"label''  function 

When  you  pair  a label  with  a menu  function,  that  label  appears  as  a menu  item.  You  can 
invoke  the  function  by  selecting  the  item  from  the  menu  using  the  pointer.  For  example,  the 
line: 


"Refresh"  f. refresh 

sets  up  the  Refresh  menu  item,  which  can  be  selected  from  the  Root  Menu  as  discussed  ear- 
lier in  this  appendix.  (Again,  the  function  performed  is  obvious  from  the  function  name.)  As 
we’ll  see  later,  it’s  easy  to  add  items  to  the  Root  Menu  by  adding  lines  of  label/function  pairs. 

Because  Window  Menu  items  can  be  invoked  in  a variety  of  ways,  the  syntax  for  defining 
items  is  more  complicated.  The  following  text  defines  the  Window  Menu: 
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# Default  Window  Menu  Description 


Menu  DefaultWindowMenu 
{ 

"Restore"  R 

MwmWindowMenu 

Alt<Key>F5 

f . normalize 

"Move" 

M 

Alt<Key>F7 

f .move 

"Size" 

_S 

Alt<Key>F8 

f . resize 

"Minimize" 

n 

Alt<Key>F9 

f .minimize 

"Maximize" 

X 

Alt<Key>F10 

f . maximize 

"Lower" 

_L 

Alt<Key>F3 

f . lower 

no-label 

"Close" 

} 

_C 

Alt<Key>F4 

f . separator 
f .kill 

The  syntax  of  each  menu  item  is  as  follows: 

"label"  mnemonic  accelerator  function 

(The  mnemonic  and  accelerator  fields  are  optional.)  Like  the  Root  Menu,  each  item  on  the 
Window  Menu  can  be  invoked  by  selecting  its  label  with  the  pointer.  In  addition,  there  are 
two  shortcuts  defined  for  invoking  the  function,  a mnemonic  and  an  accelerator.  As  you  may 
recall,  a mnemonic  is  a unique  letter  abbreviation  for  the  menu  item  label.  On  the  menu, 
mnemonic  abbreviations  are  underlined;  thus  an  underscore  precedes  each  mnemonic  defini- 
tion in  the  system.mwmrc  file.  Once  the  Window  Menu  is  displayed,  you  can  select  an  item  by 
typing  its  mnemonic  abbreviation.  Similarly,  you  can  invoke  the  function  without  displaying 
the  menu,  simply  by  typing  the  accelerator  keys  (by  default,  the  Alt  key  plus  a function  key). 

Now  let’s  see  how  one  of  the  Window  Menu  definition  lines  fits  this  template: 

"Move"  M Alt<Key>F7  f .move 

The  menu  item  label  is  Move.  Selecting  the  item  invokes  the  f .move  function.  The 
mnemonic  “m”  or  the  accelerator  key  combination  Alt-F7  can  also  be  used  to  invoke  the 
function. 

Key  Bindings 

The  second  section  of  the  system.mwmrc  file  binds  keystroke  combinations  to  window  man- 
ager functions. 

Like  the  menu  definintion  section,  the  key  bindings  section  of  the  file  is  titled  and  bracketed: 

Keys  Section Tit le 
{ 

key  bindings  defined 
} 

The  section  type  is  Keys.  The  section  title  in  the  system.mwmrc  file  is  DefaultKey- 
Bindings.  This  title  can  also  be  specified  as  the  value  of  the  mwm  resource  key- 
Bindings  in  your  Xresources  file.  However,  since  these  bindings  are  used  by  default,  this 
is  not  necessary. 

Using  the  section  title  as  a resource  becomes  significant  when  you  want  to  create  an  alterna- 
tive set  of  bindings.  Hypothetically,  you  could  add  another  set  of  bindings  with  a different 
title  to  your  .mwmrc  file.  Then  specify  this  title  as  the  value  of  the  keyBindings  resource 
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in  your  Xresources  file.  If  you  add  the  following  resource  specification  to  your  X resources 
file,  MyButtonBindings  replace  Def aultButtonBindings  for  all  client  applica- 
tions running  with  mwm: 

Mwm*keyBindings : MyButtonBindings 

If  you  want  to  use  different  sets  of  bindings  for  different  applications,  you  can  add  an  appli- 
cation name  between  the  parts  of  the  resource  specification.  For  example,  if  you  want  My- 
ButtonBindings to  apply  only  to  xterm  windows  running  with  mwm,  you  could  enter  the 
following  resource  line: 

Mwm*xterm*keyBindings : MyButtonBindings 

Then  Def  aultButtonBindings  would  still  apply  to  all  applications  other  than  xterm. 

A non-obvious  principle  behind  a key/function  (or  button/function)  binding  is  that  in  order 
for  the  keys  (or  buttons)  to  invoke  the  function,  the  pointer  must  be  in  a certain  location. 
This  location  is  known  as  the  context.  For  mwm,  the  most  commonly  used  contexts  are: 
root,  frame,  window,  and  icon.  The  window  context  refers  to  the  entire  window, 
including  the  frame.  (There  are  a few  more  specific  contexts,  such  as  border,  but  they  are 
not  used  in  the  system.mwmrc  file.  See  the  mwm  reference  page  in  your  OSF/Motif  docu- 
mentation for  details.) 

Some  functions  can  be  invoked  if  the  pointer  is  in  more  than  one  context.  For  example,  as 
we’ve  seen,  you  can  display  the  Window  Menu  from  either  a window  or  an  icon  using  the 
keyboard  shortcuts  Meta-space  or  Shift-Escape.  The  action  involved  is  f .post  wmenu 
and  the  window  and  the  icon  are  the  pointer  contexts  from  which  this  action  can  be  per- 
formed. These  keyboard  shortcuts  are  defined  in  the  key  bindings  section  of  the  sys- 
tem.mwmrc file  as  follows: 

Shif t<Key>Escape  icon  I window  f.postwmenu 
Meta<Key>space  icon | window  f.postwmenu 

Upon  examining  these  lines,  we  can  discern  the  template  for  a key  binding: 

[modifier Jceys]<KQy>key_name  context  function 

Each  binding  can  have  one  or  more  modifier  keys  (modifiers  are  optional)  and  must  have  a 
single  primary  key  (signaled  by  the  word  <Key>  in  angle  brackets)  to  invoke  the  function.  In 
the  first  specification,  Shift  is  the  modifier  and  Escape  is  the  primary  key.  In  the  second  spec- 
ification, Meta  is  the  modifier  and  space  is  the  primary  key.  Both  specifications  have  two 
acceptable  pointer  contexts:  either  a window  or  an  icon.  And  both  bindings  are  mapped  to 
the  same  action,  f . post_wmenu,  which  displays  the  Window  Menu. 

Button  Bindings 

The  key  bindings  section  of  the  file  is  also  titled  and  bracketed: 

Buttons  Sect  ion  Title 
{ 

button  bindings  defined 
} 
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The  section  type  is  Buttons.  The  system.mwmrc  file  contains  three  sets  of  button  bindings 
with  the  section  titles: 

DefaultButtonBindings 
ExplicitButtonBindings 
Point erButtonBindings 

Button  bindings  clearly  illustrate  the  need  to  coordinate  your  Xresources  and  .mwmrc  files. 
The  three  sets  of  button  bindings  correspond  to  three  possible  settings  for  the  resource 
buttonBindings.  The  default  setting  for  the  resource  is: 

Mwm*buttonBindings : DefaultButtonBindings 

specifying  that  the  DefaultButtonBindings  are  used. 

You  can  specify  that  one  of  the  other  sets  of  button  bindings  is  to  be  used  by  setting  this 
resource  in  your  Xresources  file.  For  example,  if  you  add  the  following  specification  to  your 
resource  file: 

Mwm*buttonBindings : ExplicitButtonBindings 

mwm  will  use  those  bindings  that  come  under  the  heading  ExplicitButtonBindings 
in  the  .mwmrc  file. 

Be  aware  that  if  you  do  specify  different  button  bindings,  the  value  of  the  resource  must 
exactly  match  the  title  associated  with  the  bindings,  or  the  bindings  will  not  take  effect. 

The  syntax  for  a button  binding  specification  is  very  similar  to  that  of  a key  binding: 

[modifier _key]<button_event>  context  function 

Each  binding  can  have  one  or  more  modifier  keys  (modifiers  are  optional)  and  must  have  a 
single  button  event  (enclosed  in  angle  brackets)  to  invoke  the  function.  The  motion  that 
comprises  each  button  event  should  be  fairly  obvious.  (A  list  of  acceptable  button  events 
appears  on  the  mwm  reference  page  in  your  OSF/Motif  documentation.) 

Now  let’s  see  how  the  button  binding  syntax  relates  to  the  default  button  bindings  in  the  sys- 
tem.mwmrc  file: 


Buttons  DefaultButtonBindings 
{ 


<BtnlDown> 

<Btn2Down> 

<BtnlDown> 

Meta<BtnlDown> 

Meta<Btn2Down> 

Meta<Btn3Down> 


frame  I icon 
frame | icon 
root 

window | icon 
window | icon 
window | icon 


f . raise 
f . post_wmenu 
f.menu  RootMenu 
f . lower 
f . resize 
f . move 


The  first  specification  is  familiar.  It  indicates  that  the  event  of  pressing  down  the  first  pointer 
button  while  the  pointer  is  in  a window  frame  or  an  icon  performs  the  action  of  raising  the 
window  or  icon,  respectively. 


Most  of  the  other  default  button  bindings  reveal  ways  to  perform  mwm  functions  that  were 
not  covered  in  the  first  half  of  this  appendix.  Upon  closer  examination,  you  should  be  able  to 
figure  out  these  bindings  and  what  they  do.  The  second  binding  reveals  still  another  way  to 
display  the  Window  Menu,  by  pressing  the  second  pointer  button  on  a window  frame  or  an 
icon. 
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The  third  binding  is  also  familiar,  and  illustrates  the  use  of  the  f . menu  function.  As  previ- 
ously mentioned,  the  f . menu  function  is  used  to  associate  a menu  with  the  key  or  button 
binding  that  is  used  to  display  it  The  following  binding  specifies  that  the  Root  Menu  is 
displayed  by  pressing  and  holding  down  the  first  pointer  button  on  the  root  window: 

<BtnlDown>  root  f.menu  RootMenu 

Notice  that  the  function  requires  an  argument,  the  menu  name  (RootMenu),  which  also 
appears  in  the  first  line  of  the  menu  definition.  This  correspondence  is  required — f .menu 
needs  to  know  which  menu  to  display. 

The  other  default  button  bindings  perform  useful  (though  not  obvious)  functions.  Each  speci- 
fies holding  down  the  Meta  key  and  simultaneously  pressing  a different  pointer  button  while 
the  pointer  is  on  a window  or  icon.  Holding  down  the  Meta  key  and  pressing  the  first  pointer 
button  on  a window  or  icon  lowers  the  window  or  icon  to  the  bottom  of  the  stack.  Holding 
down  the  Meta  key  and  pressing  the  second  or  third  pointer  button  enables  you  to  resize  or 
move  the  object,  respectively. 


Customizing  the  Root  Menu 


You  can  add  items  to  the  Root  Menu  simply  by  adding  lines  of  the  format: 

“ label " function 

within  the  menu  definition  section  of  your  .mwmrc  file. 

The  f . exec  function  allows  you  to  execute  system  commands  from  a menu.  In  the  default 
Root  Menu,  the  New  Window  command  uses  the  f . exec  function  to  execute  the  system 
command  xterm  &. 


# Root  Menu  Description 
Menu  RootMenu 


{ 

"Root  Menu" 
No-label 
"New  Window" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 
no-label 
"Restart ..." 

} 


f . title 
f . separator 
f.exec  "xterm  &" 
f . circle_up 
f . circledown 
f . refresh 
f . separator 
f . restart 


To  create  a menu  item  labeled  Clock  that  opens  an  xclock  window  on  your  display,  simply 
add  a line  to  your  .mwmrc  file,  as  shown  here: 


# Root  Menu  Description 
Menu  RootMenu 


"Root  Menu" 
No-label 
"New  Window" 
"Clock" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 


f .title 
f . separator 
f.exec  "xterm  &" 
f.exec  "xclock  &" 
f . circle_up 
f . circle  down 
f . refresh 
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no-label 
"Restart . . . 


f . separator 
f . restart 


} 

You  can  also  edit  (or  remove)  existing  menu  items.  For  example,  if  you  want  to  run  a termi- 
nal emulator  program  other  than  xterm,  you  can  edit  the  menu  item  definition  in  your  .mwmrc 
file.  Say  you  want  to  run  the  hpterm  terminal  emulator  (developed  by  Hewlett-Packard),  you 
would  edit  your  menu  specification  to  look  like  this: 


# Root  Menu  Description 
Menu  RootMenu 


{ 

"Root  Menu" 
No-label 
"New  Window" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 
no-label 
"Restart ..." 

} 


f .title 
f . separator 
f.exec  "hpterm  & 
f . circle_up 
f . circledown 
f . refresh 
f . separator 
f . restart 


Creating  New  Menus 

Keep  in  mind  that  mwm  also  allows  you  to  specify  entirely  new  menus  in  your  .mwmrc  file. 
A new  menu  can  be  separate  from  all  existing  menus,  or  it  can  be  a submenu  of  an  existing 
menu.  (Submenus  are  described  in  the  following  section,  “Cascading  Menus.”) 

If  you  want  to  create  a new,  independent  menu,  it  must  conform  to  the  menu  specification 
syntax  discussed  earlier.  Items  must  invoke  predefined  window  manager  functions. 

The  .mwmrc  file  must  also  specify  how  the  menu  will  be  displayed  and  in  what  context.  This 
involves  associating  a key  or  button  with  the  f . menu  function.  Say  you’ve  specified  a new 
menu,  titled  GamesMenu,  that  runs  various  game  programs,  each  in  its  own  window.  (The 
f . exec  function  would  be  used  to  define  each  item.)  The  following  button  binding  speci- 
fies that  pressing  the  second  pointer  button  on  the  root  window  causes  the  Games  Menu  to  be 
displayed: 

<Btn2Down>  root  f.menu  GamesMenu 


Cascading  Menus 

mwm  also  allows  you  to  create  submenus,  generally  known  as  cascading  menus  because  they 
are  displayed  to  the  right  side  of  (and  slightly  lower  than)  another  menu.  You  define  a sub- 
menu just  as  you  would  any  other,  using  the  syntax  rules  discussed  earlier.  The  following 
lines  create  a Utilities  Menu  that  invokes  several  “desktop”  clients  and  one  game: 

Menu  UtilitiesMenu 
{ 

"Utilities  Menu"  f. title 
No-label  f. separator 

"Clock"  f.exec  "xclock  &" 

"System  Load"  f.exec  "xload  &" 
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"Calculator"  f.exec  "xcalc  &" 

"Manpage  Browser"  f.exec  "xman  &" 
"Tetris"  f.exec  "xtetris  & 


In  order  to  make  this  a submenu  of  the  Root  Menu,  you  need  to  add  an  f . menu  function  to 
the  Root  Menu.  This  f . menu  function  must  be  coupled  with  the  correct  submenu  title: 


# Root  Menu  Description 
Menu  RootMenu 


"Root  Menu" 
No-label 
"New  Window" 
"Shuffle  Up" 
"Shuffle  Down" 
"Refresh" 
"Utilities" 
no-label 
"Restart ..." 


f .title 
f . separator 
f.exec  "xterm 
f .circle_up 
f . circle_down 
f . refresh 
f . menu 
f . separator 
f . restart 


&" 


UtilitiesMenu 


} 


After  you  specify  the  preceding  menus  in  your  .mwmrc  file  (and  restart  mwm),  display  the 
Root  Menu.  It  will  feature  a new  item,  labeled  Utilities.  Since  this  item  is  actually  a pointer  to 
a submenu,  it  will  be  followed  by  an  arrow  pointing  to  the  right,  as  in  Figure  C-13. 


Figure  C-13.  An  arrow  pointing  to  the  right  indicates  a submenu 


If  you  drag  the  pointer  down  the  Root  Menu  to  the  Utilities  item,  the  submenu  will  appear  to 
cascade  to  the  right.  Figure  C-14  shows  it  appearing. 

If  you  release  the  pointer  button,  both  menus  will  remain  displayed  and  the  Utilities  item  and 
the  first  item  on  the  Utilities  Menu  will  be  highlighted  by  a box.  You  can  then  select  an  item 
from  the  Utilities  Menu  by  moving  the  pointer  to  the  item  and  clicking  the  first  button. 
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Figure  C-14.  Utilities  submenu  of  the  Root  Menu 

Keep  in  mind  that  you  can  create  several  submenus  beneath  a single  menu  and  that  menus 
can  cascade  several  levels,  though  such  complexity  is  not  necessarily  desirable. 


Setting  mwm  Resources 

The  Motif  window  manager  provides  dozens  of  resources  that  control  the  appearance  and 
functionality  of  the  window  manager,  its  component  features,  and  other  clients  running  with 
it.  mwm  resources  should  be  entered  in  your  Xresources  file  and  take  effect  when  the 
resources  have  been  loaded  into  the  server  and  mwm  has  been  started  or  restarted.  See  Chap- 
ter 9,  Setting  Resources , for  syntax  information  and  instructions  on  how  to  load  resources 
using  the  xrdb  client.  See  “Activating  Changes  to  the  Window  Manager”  for  information 
about  running  mwm  with  the  new  resource  settings. 

mwm  resources  are  considered  to  fall  into  three  categories: 

1.  mwm  component  appearance  resources.  These  resources  set  the  characteristics  of 
mwm' s,  component  features,  such  as  the  window  frame,  menus,  and  icons. 

2.  mn'm-specific  appearance  and  behavior  resources.  These  resources  set  characteristics 
of  the  window  manager  client,  such  as  focus  policy,  key  and  button  bindings,  and  so 
forth. 

3.  Client-specific  resources.  These  mwm  resources  can  be  used  to  set  the  appearance  and 
behavior  of  a particular  client  or  class  of  clients. 


622 


X Window  System  User’s  Guide 


Under  these  categories  fall  dozens  of  mwm  resources.  The  sheer  number  of  resources  makes 
it  impractical  for  all  of  them  to  be  discussed  here.  (You  could  spend  quite  a long  time  cus- 
tomizing mwm  in  this  way,  if  you  had  the  time  and  inclination!)  In  the  following  sections,  we 
discuss  the  three  categories  of  resources  in  somewhat  greater  detail.  We’ll  then  take  a look  at 
two  of  the  more  powerful  and  useful  resources,  keyboardFocusPolicy  and  use- 
iconBox,  which  set  the  focus  policy  and  set  up  mwm  to  use  an  icon  box,  respectively.  For  a 
comprehensive  list  of  available  resources,  see  the  mwm  reference  page  in  your  OSF/Motif 
documentation. 

Component  Appearance  Resources 

The  Motif  window  manager  can  be  considered  to  be  made  up  of  components:  client  window 
frames,  menus,  icons,  and  what  are  known  as  feedback  boxes.  An  example  of  a feedback  box 
is  the  box  that  appears  so  that  you  can  confirm  or  cancel  a Restart  command  from  the  Root 
Menu.  (See  ‘The  Root  Menu”  earlier  in  this  appendix.) 

Certain  resources  allow  you  to  specify  the  appearance  of  one  or  all  of  these  mwm  component 
features.  In  specifying  the  resource  setting,  you  can  use  the  name  of  one  of  the  features  as 
part  of  the  resource  name.  For  example,  one  of  the  most  useful  component  appearance 
resources  is  background,  which,  as  we  know  from  Chapter  8,  specifies  the  background 
color.  You  can  specify  a resource  that  sets  the  background  color  of  any  of  the  mwm  compo- 
nents. The  following  resource  specification  sets  the  background  color  of  all  client  window 
frames  to  light  blue: 

Mwm*client ‘background : lightblue 

Table  C-2  summarizes  the  resource  name  that  corresponds  to  each  of  the  mwm  components: 

Table  C-2.  Resource  Names  Corresponding  to  mwm  Components 


Component 

Resource  name 

Menu 

menu 

Icon 

icon 

Client  window  frame 

client 

Feedback  box 

feedback 

Thus,  to  set  the  background  color  of  feedback  boxes  to  sea  green,  you’d  use  the  following 
resource: 

Mwm*feedback*foreground : seagreen 

Of  course,  if  you  omit  any  specific  component  from  the  resource  specification,  it  applies  to 
all  components.  Thus,  the  following  specification  sets  the  background  color  of  all  window 
frames,  feedback  boxes,  icons,  and  menus  to  light  grey: 

Mwm* foreground : lightgrey 
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mwm-SpecIflc  Appearance  and  Behavior  Resources 

The  mwm-specific  resources  control  aspects  of  what  you  probably  think  of  as  the  window 
manager  application  itself,  features  such  as  the  focus  policy,  whether  windows  are  placed  on 
the  display  automatically  or  interactively,  which  set(s)  of  button  and  key  bindings  are  used, 
whether  an  icon  box  is  used,  and  so  forth. 

The  syntax  of  mwm-specific  resource  specifications  is  very  simple:  the  mwm  class  name  con- 
nected by  a loose  binding  to  the  resource  variable  name,*  shown  here: 

Mwm*clientAutoPlace : false 

This  resource  establishes  the  behavior  that  the  user  will  interactively  place  client  windows  on 
the  display.  (The  default  is  true,  meaning  mwm  places  them  automatically.) 

Two  of  the  mwm-specific  resources  bring  up  an  issue  of  coordination  between  the 
Xresources  and  .mwmrc  files.  Remember,  the  default  .mwmrc  file  contains  three  sets  of  but- 
ton bindings: 

DefaultButtonBindings 
ExplicitButtonBindings 
Point erButtonBindings 

These  three  sets  of  button  bindings  correspond  to  three  possible  settings  for  the  resource  vari- 
able buttonBindings.  If  your  resource  file  contains  the  following  setting: 

Mwm*buttonBindings : ExplicitButtonBindings 

mwm  will  use  those  bindings  that  come  under  the  heading  ExplicitButtonBindings 
in  the  .mwmrc  file. 

Similarly,  the  resource  variable  keyBindings  should  be  coordinated  to  match  the  key 
bindings  in  the  .mwmrc  file.  Since  the  default  .mwmrc  file  has  only  one  set  of  key  bindings, 
named  Def aultKeyBindings,  and  the  keyBindings  resource  also  sets  this  by 
default,  coordination  should  not  be  an  issue  unless  you  create  a new  set  of  key  bindings  with 
a different  name. 

Two  of  the  most  useful  and  powerful  mwm-specific  resources  set  the  keyboard  focus  policy 
and  specify  that  icons  be  stored  in  an  icon  box.  We’ll  discuss  the  use  and  advantages  of  these 
resources  later  in  this  appendix. 

Client-Specific  Resources 

Some  mwm  resources  can  be  set  to  apply  to  certain  client  applications  or  classes  of  applica- 
tions. These  resources  generally  have  the  form: 

Mwm* application* resource_variable: 

where  application  can  be  an  instance  name  or  a class  name.t  Be  aware  that  the  appli- 
cation name  is  optional.  If  you  omit  an  application  name,  the  resource  applies  to  all  clients. 


*Loose  and  tight  bindings  are  described  in  Chapter  9,  Setting  Resources. 
flnstance  and  class  names  are  described  in  Chapter  9,  Setting  Resources. 
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Many  of  the  client-specific  resources  provide  what  might  be  considered  advanced  customiza- 
tion. For  example,  a combination  of  resources  allows  you  to  specify  your  own  bitmap  as  the 
image  for  a client  icon.  The  average  user  will  probably  not  need  most  of  these  resources. 

One  client-specific  resource  users  might  be  interested  in  is  called  f ocusAutoRaise.  This 
resource,  true  by  default,  causes  the  active  window  (the  window  receiving  input  focus)  to  be 
raised  to  the  top  of  the  stack.  If  you  are  using  explicit  (click-to-type)  focus  (also  the  default), 
this  behavior  is  clearly  very  desirable.  However,  if  you  change  the  focus  policy  to  pointer 
focus  (as  we’ll  describe  in  the  following  section),  having  f ocusAutoRaise  on  can  make 
the  display  seem  chaotic. 

When  pointer  focus  is  active,  as  you  move  the  pointer  across  the  display,  the  focus  changes 
from  window  to  window  based  on  the  location  of  the  pointer,  often  a desirable  feature.  How- 
ever, if  focusAutoRaise  is  still  true,  each  time  the  pointer  moves  into  a window,  the 
window  will  be  moved  to  the  front  of  the  display.  Simply  moving  the  pointer  across  a 
screenful  of  windows  can  create  a distracting  shuffling  effect!  If  you  set  the  focus  policy  to 
pointer,  we  suggest  you  also  set  focusAutoRaise  to  false,  as  in  the  following  example: 

Mwm*f ocusAutoRaise : false 

Since  an  application  name  is  omitted  from  this  resource  specification,  it  applies  to  all  clients. 
To  change  the  behavior  only  for  the  class  of  xterm  windows,  you  could  specify: 

Mwm*XTerm*focusAutoRaise : false 

Of  course,  suppressing  focusAutoRaise  with  pointer  focus  is  just  our  preference.  You 
may  want  to  experiment  a while  to  see  how  you  like  working  with  it. 

Setting  the  Focus  Policy 

The  most  common  resource  users  will  probably  want  to  set  controls  mwm's  keyboard  focus 
policy.  By  default,  mwm  has  explicit  (or  click-to-type)  focus,  which  is  set  using  the  follow- 
ing resource: 

Mwm*keyboardFocusPolicy : explicit 

To  change  the  keyboard  focus  policy  from  explicit  to  pointer  focus  (that  is,  focus  follows  the 
movement  of  the  pointer),  enter  the  following  line  in  your  X resources  file: 

Mwm*keyboardFocusPolicy : pointer 
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Using  an  Icon  Box 


One  of  the  most  interesting  (and  desirable)  features  mwm  can  provide  is  a window  in  which 
icons  can  be  organized  on  the  display.  This  window  is  known  as  an  icon  box,  and  is  pictured 
in  Figure  C-15  below. 


Figure  C-15.  An  icon  box 


As  we’ll  see,  in  addition  to  organizing  icons  neatly  on  the  display,  the  icon  box  also  provides 
a few  window  manipulation  functions. 

You  can  set  up  mwm  to  provide  an  icon  box  automatically  by  specifying  the  following 
resource  in  your  Xresources  file: 

Mwm*useIconBox : true 

II  this  resource  is  included  in  your  Xresources  file  (and  the  resources  have  been  loaded  as 
described  in  Chapter  9,  Setting  Resources),  mwm  will  provide  an  icon  box  when  it  is  started 
(or  restarted).  Other  resources  can  be  used  to  customize  the  size,  appearance  and  location  of 
the  icon  box,  as  well  as  the  window’s  title.  By  default,  the  icon  box  is  six  icons  wide  by  one 
icon  high  (the  size  of  individual  icons  depends  on  other  mwm  resources)  and  is  located  in  the 
lower  left  hand  comer  of  the  display. 

The  horizontal  and  vertical  scrollbars  within  the  icon  box  suggest  a significant,  albeit  non- 
obvious,  feature.  Icons  can  extend  beyond  the  visible  bounds  of  the  icon  box.  If  more  than 
six  icons  are  present  in  the  default  size  box,  you  can  view  them  using  the  scrollbars.  (See 
Chapter  4,  The  xterm  Terminal  Emulator,  for  instructions  on  using  scrollbars.)  Keep  in  mind 
that  if  icons  do  extend  beyond  the  visible  bounds  of  the  box,  the  appearance  of  the  scrollbars 
will  indicate  it. 

The  presence  of  an  icon  box  changes  the  way  icons  are  used  on  the  display.  If  you  are  using 
mwm  without  an  icon  box,  only  those  windows  that  have  been  iconified  are  represented  by 
icons  on  the  display.  If  you  are  using  mwm  with  an  icon  box,  all  windows  on  the  display  are 
represented  by  icons  that  are  stored  in  the  box,  whether  or  not  the  windows  are  in  an  iconfied 
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When  a client  window  is  started,  the  window  appears  on  the  display  and  a corresponding 
icon  appears  in  the  icon  box.  However,  an  icon  that  represents  a window  currently  visible  on 
the  display  has  a different  appearance  than  an  actual  icon  (that  is,  an  iconified  window).  An 
icon  corresponding  to  a window  currently  on  the  display  appears  flatter  and  less  defined  than 
the  image  of  an  iconified  window.  The  former  probably  has  fewer  lines  in  its  outer  border.  If 
you  set  up  mwm  to  use  an  icon  box,  the  differing  appearance  of  these  two  types  of  icons 
should  be  obvious. 

Somewhat  similar  to  a menu  item  in  a lighter  typeface,  the  flatter,  less  defined  icon  suggests 
that  it  is  not  available  to  be  chosen.  In  a sense,  this  is  true.  Since  the  flat  icon  is  not  an  iconi- 
fied window,  but  merely  an  image,  it  is  not  available  to  be  converted  back  to  a window.  The 
icon  box  in  Figure  C-15  contains  two  iconified  windows  ( xclock  and  the  first  xterm ) and  four 
icons  representing  windows  currently  visible  on  the  display. 

You  can  perform  some  manipulations  by  clicking  on  icons  in  the  icon  box.  If  you  double 
click  on  an  iconified  window  using  the  first  pointer  button,  the  icon  is  converted  back  to  a 
window.  If  you  double  click  on  an  icon  representing  an  active  window  on  the  display,  the 
corresponding  window  is  raised  to  the  front  of  the  display. 

However,  an  icon  box  limits  the  way  you  can  work  with  the  Window  Menu.  (It  also  changes 
one  of  the  menu’s  options.)  If  you  are  using  an  icon  box,  you  cannot  display  the  Window 
Menu  from  an  individual  icon  and  manipulate  that  icon.*  Instead,  when  you  display  the 
menu  from  the  icon  box,  the  menu  commands  apply  to  the  box  itself  (which  is  actually  a win- 
dow). You  can  display  the  menu  from  the  icon  box  using  any  of  the  methods  described  in  the 
section  “Manipulating  Windows  Using  the  Window  Menu”  earlier  in  this  appendix.  For 
example,  if  you  use  the  keyboard  shortcut  Meta-space,  the  menu  is  displayed  above  the  Win- 
dow Menu  command  button  in  the  upper  left  hand  comer  of  the  icon  box  frame. 

When  displayed  from  the  icon  box,  the  Window  Menu  Close  item  is  replaced  by  an  item 
called  Packlcons  (mnemonic  “p”,  accelerator  Alt+F12|).  Packlcons  rearranges  the  icons  in 
the  box  to  fill  in  empty  slots.  This  is  useful  when  icons  are  removed  from  the  box  or  the  box 
is  resized. 

When  you  remove  a window,  the  corresponding  icon  is  removed  from  the  box,  leaving  an 
empty  slot.  Packlcons  will  move  any  icons  that  are  to  the  right  of  the  slot  one  space  to  the 
left  to  fill  the  hole.  If  you  resize  the  icon  box,  Packlcons  will  arrange  the  icons  to  fit  the  new 
window  in  an  optimal  way.  For  instance,  say  we  resize  the  icon  box  in  Figure  C-15  so  that  it 
is  only  three  icons  wide,  but  twice  as  high,  as  in  Figure  C-16.  The  first  three  icons  from  the 
box  appear;  the  second  three  are  obscured,  tt 


*mwm  is  documented  to  display  the  Window  Menu  from  an  icon  if  you  press  the  third  pointer  button.  However,  this 
does  not  seem  to  work  according  to  the  specifications.  The  1.1  version  of  mwm,  scheduled  for  release  in  June  of 
1 990,  may  provide  this  functionality. 

fObviously,  if  your  keyboard  has  only  ten  function  keys,  you  cannot  use  the  Alt+F12  accelerator, 
tt  When  you  resize  the  icon  box,  you’ll  notice  the  resize  action  has  a tendency  to  jump  the  width  or  height  of  an  icon 
at  a time.  The  box  must  be  resized  exactly  to  fit  a number  of  icons  wide  and  a number  high,  though  there  are  no  ob- 
vious limitations  as  to  the  numbers.  Basically,  you  can  have  an  icon  box  of  any  size,  even  one  icon  high  and  wid 
and  display  the  other  icons  using  the  scrollbars. 
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Figure  C-16.  In  the  resized  icon  box,  only  three  icons  are  visible 

Notice  the  horizontal  scrollbar  at  the  bottom  of  the  window,  indicating  that  the  other  three 
icons  are  still  to  the  right  of  these  and  thus  not  viewable  in  the  resized  box.  If  you  place  the 
pointer  on  the  scrollbar,  hold  down  the  first  button  and  drag  the  scrollbar  to  the  right,  the  hid- 
den icons  will  be  revealed. 

In  order  to  rearrange  the  icons  to  better  fill  the  new  shape  box,  use  the  Packlcons  menu  item. 
Figure  C-17  shows  the  icon  box  after  you’ve  selected  Packlcons. 


Figure  C-17.  Packlcons  menu  item  rearranges  icons  in  resized  box 
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If  you  want  to  reorganize  icons  in  the  box  yourself,  without  Packlcons,  this  is  also  possible. 
You  can  actually  move  icons  into  adjacent  empty  slots  using  the  pointer.  Just  hold  down  the 
first  pointer  button  on  the  icon  and  drag  it  into  the  next  slot.  If  you  first  make  the  icon  box 
larger,  so  that  there  are  several  empty  spaces,  you’ll  find  you  can  radically  reorganize  icons. 
Once  you’ve  arranged  them  as  you  like,  you  resize  the  box  to  fit  the  icons — or  perhaps  make 
it  even  smaller  and  view  the  obscured  icons  using  the  scrollbars. 
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Standard  Cursors 


This  appendix  shows  the  standard  cursor  images  that  can  be  used  by  X 
programs. 


I 


D 

Standard  Cursors 


Table  D-l  lists  the  cursors  available  in  the  standard  distribution  of  X from  MIT;  the  cursor 
shapes  themselves  are  pictured  in  Figure  D- 1 . The  cursor  shapes  in  the  standard  distribution 
are  the  same  in  Release  3 and  Release  4. 

To  specify  a cursor  as  an  argument  to  a command  line  option,  as  the  value  of  a resource  vari- 
able, etc.,  strip  the  XC_  prefix  from  the  symbol  name.  For  example,  to  specify  the 
XC_sailboat  cursor  as  the  xterm  pointer,  you  could  enter  the  command: 

% xterm  -xrm  ' xterm*pointerShape : sailboat' 

Each  cursor  has  an  associated  numeric  value  (to  the  right  of  the  symbol  name  in  the  table). 
You  may  notice  that  the  values  skip  the  odd  numbers.  Each  cursor  is  actually  comprised  of 
two  font  characters:  the  character  that  defines  the  shape  (pictured  in  Figure  D-l),  and  a mask 
character  (not  shown)  that  sets  the  cursor  shape  off  from  the  root  (or  other)  window.  (More 
precisely,  the  mask  selects  which  pixels  in  the  screen  around  the  cursor  are  disturbed  by  the 
cursor.)  The  mask  is  generally  the  same  shape  as  the  character  it  underlies,  but  is  one  pixel 
wider  in  all  directions. 

To  get  an  idea  of  what  masks  look  like,  display  the  entire  cursor  font  using  the  command: 

% xfd  -fn  cursor 
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Table  D-1.  Standard  Cursor  Symbols 


Symbol 

Value 

Symbol 

Value 

XCX  cursor 

0 

XC  11  angle 

76 

XC_arrow 

2 

XC  lr  angle 

78 

XC  based  arrow  down 

4 

XC  man 

80 

XC  based  arrow  up 

6 

XC  middlebutton 

82 

XC_boat 

8 

XC  mouse 

84 

XC_bogosity 

10 

XC_pencil 

86 

XC  bottom  left  c o r ne r 

12 

XC_pirate 

88 

XC_bottom  right  corner 

14 

XC_plus 

90 

XC_bottom  side 

16 

XC  question  arrow 

92 

XC_bottom  tee 

18 

XC_right__pt  r 

94 

XC_box  spiral 

20 

XC  right  side 

96 

XC  center_ptr 

22 

XC_right  tee 

98 

XC_circle 

24 

XC  rightbutton 

100 

XC_clock 

26 

XC_rtl  logo 

102 

XC_coffee  mug 

28 

XC  sailboat 

104 

XC  cross 

30 

XC  sb  down  arrow 

106 

XC_cross  reverse 

32 

XC  sb  h double  arrow 

108 

XC_crosshair 

34 

XC  sb  left  arrow 

110 

XC_diamond  cross 

36 

XC  sb  right  arrow 

112 

XC_dot 

38 

XC  sb  up  arrow 

114 

XC_dotbox 

40 

XC  sb  v double  arrow 

116 

XC_double  arrow 

42 

XC  shuttle 

118 

XC_draft  large 

44 

XC  sizing 

120 

XC_draft  small 

46 

XC  spider 

122 

XC_draped  box 

48 

XC  spraycan 

124 

XC_exchange 

50 

XC  star 

126 

XC  fleur 

52 

XC  target 

128 

XC_gobbler 

54 

XC  tcross 

130 

XC  gumby 

56 

XC  top  left  arrow 

132 

XC_handl 

58 

XC  top  left  corner 

134 

XC_hand2 

60 

XC  top  right  corner 

136 

XC  heart 

62 

XC  top  side 

138 

XC_icon 

64 

XC  top  tee 

140 

XC_iron  cross 

66 

XC  trek 

142 

XC_left_ptr 

68 

XC  ul  angle 

144 

XC_left  side 

70 

XC  umbrella 

146 

XC_left  tee 

72 

XC  ur  angle 

148 

XC_lef t but ton 

74 

XC_watch 

150 

XC_xterm 

152 
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Release  3 and  4 Standard  Fonts 


This  appendix  shows  the  standard  display  fonts  available  in  Release  4 of  the 
MIT  X distribution.  The  images  contained  in  this  appendix  are  window 
dumps  created  with  our  own  program,  called  xshowfonts,  the  code  for  which 
is  included. 


Release  3 and  4 
Standard  Fonts 
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Release  3 and  4 Standard  Fonts 


This  appendix  includes  pictures  of  some  representative  fonts  from  the  standard  X distribution 
in  Releases  3 and  4.  Not  every  font  may  be  supported  by  particular  server  vendors,  and  some 
vendors  may  supplement  the  set 


The  standard  Release  3 and  4 fonts  are  stored  in  three  directories: 


Directory 

Contents 

lusrllib/Xl  1 /fonts/misc 

lusr/lib/Xl  1 /font  s/75  dpi 
lusrlliblXl  1 Ifontsll  00dpi 

Six  fixed-width  fonts  (also  available  in  Release  2), 
the  cursor  font,  other  miscellaneous  fonts. 

Fixed-  and  variable-width  fonts,  75  dots  per  inch. 
Fixed-  and  variable- width  fonts,  100  dots  per  inch. 

Tables  E-l  through  E-3  list  the  fonts  in  each  of  the  three  Release  4 font  directories.  Tables 
E-4  through  E-6  list  the  fonts  in  each  of  the  three  Release  3 font  directories.  The  first  column 
lists  the  name  of  the  file  in  which  the  font  is  stored  (without  the  .snf  extension);  the  second 
column  lists  the  actual  font  name.  See  Chapter  5,  Font  Specification,  for  information  about 
font  naming  conventions. 

PICTURES  of  the  different  font  families  supplied  in  the  MIT  XI 1 distribution  appear  on  sub- 
sequent pages.  We  show  just  the  fonts  in  the  75dpi  directory.  The  100dpi  directory  contains 
the  same  fonts  stored  in  the  75dpi  directory,  but  for  100  dots  per  inch  monitors.  Keep  in 
mind  that  all  of  the  fonts  in  the  75dpi  and  100dpi  directories  are  available  in  8, 10, 12, 14, 18 
and  24-point  sizes.  Each  page  shows  fonts  of  various  sizes,  weights,  and  styles.  We  include 
the  source  for  xshowfonts.c,  the  program  we  wrote  to  make  these  displays,  at  the  end  of  the 
chapter.*  We  also  show  you,  using  yfd,  one  example  of  each  of  the  unique  character  sets 
available. 

All  of  the  characters  in  each  font  are  shown  actual  size,  as  they  would  appear  on  a 900  x 
1180  pixel,  10"  x 13.5"  screen  (Sun).  On  a screen  with  different  pixel  density,  these  fonts 
would  appear  a different  size. 


*If  you  don’t  want  to  type  this  program  in,  you  can  obtain  the  source  from  uuneLuu.net  via  anonymous  ftp  or  uucp. 
See  the  Preface  for  more  information. 
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Fonts  that  begin  with  many  blank  characters  are  shown  with  most  leading  blanks  removed. 
Therefore,  you  can’t  always  get  the  character  number  of  each  cell  in  the  font  by  counting 
from  the  first  cell  we  have  shown.  Use  xfd  to  quickly  determine  the  code  for  a particular  cell. 

Table  E-1.  Fonts  in  the  misc  Directory,  Release  4 


Filename 

Font  name 

7xl3B.snf 

8xl3B.snf 

9xl5B.snf 

6xl3B.snf 

6xl0.snf 

7xl3.snf 

8x13. snf 

kl4.snf 

7x14. snf 
7xl4rk.snf 
9x15. snf 
10x20.  snf 
5x8.snf 
6x9.snf 

6x12. snf 

6x13. snf 

clB6xl0.snf 

clB8xl0.snf 

clB6xl2.snf 

clB8xl2.snf 

clB8xl3.snf 

clB8xl4.snf 

clB9xl5.snf 

clB8xl6.snf 

clB8x8.snf 

clI6xl2.snf 

clI8x8.snf 

clR5xl0.snf 

clR6xl0.snf 

clR7xl0.snf 

clR8xl0.snf 

clR6xl2.snf 

clR7xl2.snf 

clR8xl2.snf 

clR6xl3.snf 

clR8xl3.snf 

clR7xl4.snf 

clR8xl4.snf 

clR9xl5.snf 

clR8xl6.snf 

-misc-fixed-bold-r-normal  — 13-120-75-75-c-70-iso8859-l 
-misc-fixed-bold-r-normal — 13-120-75-75-c-80-iso8859-l 
-misc-fixed-bold-r-normal  — 1 5-  140-75-75-c-90-iso8859- 1 
-misc-fixed-bold-r-semicondensed  — 13-120-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-normal  — 10-100-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-normal  — 13-120-75-75-c-70-iso8859-l 
-misc-fixed-medium-r-normal — 13-120-75-75-c-80-iso8859-l 
-misc-fixed-medium-r-normal — 14-130-75-75-c-140-jisx0208. 1983-0 
-misc-fixed-medium-r-normal  — 14-130-75-75-c-70-iso8859-l 
-misc-fixed-medium-r-normal  — 14-130-75-75-c-70-jisx0201. 1976-0 
-misc-fixed-medium-r-normal  — 1 5-  140-75-75-c-90-iso8859- 1 
-misc-fixed-medium-r-normal — 20-200-75-75-c-100-iso8859-l 
-misc-fixed-medium-r-normal — 8-80-75-75-c-50-iso8859- 1 
-misc-fixed-medium-r-normal — 9-90-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-semicondensed  — 12-1 10-75-75-c-60-iso8859-l 
-misc-fixed-medium-r-semicondensed  -13-1 20-75-75-c-60-iso8859- 1 
-schumacher-clean-bold-r-normal  — 10-100-75-75-c-60-iso8859-l 
-schumacher-clean-bold-r-normal  — 10-100-75-75-c-80-iso8859-l 
-schumacher-clean-bold-r-normal  — 12-120-75-75-c-60-iso8859- 1 
-schumacher-clean-bold-r-normal  — 12-120-75-75-c-80-iso8859-l 
-schumacher-clean-bold-r-normal  — 13-130-75-75-c-80-iso8859-l 
-schumacher-clean-bold-r-normal  — 14- 140-75-75-c-80-iso8859-l 
-schumacher-clean-bold-r-normal  — 1 5-  150-75-75-c-90-iso8859- 1 
-schumacher-clean-bold-r-normal  — 16-1 60-75-75-c-80-iso8859-l 
-schumacher-clean-bold-r-normal— 8-80-75-75-c-80-iso8859-l 
-schumacher-clean-medium-i-normal  — 12-120-75-75-c-60-iso8859-l 
-schumacher-clean-medium-i-normal— 8-80-75-75-c-80-iso8859-l 
-schumacher-clean-medium-r-normal  -10-1 00-75-75-c-50-iso8859- 1 
-schumacher-clean-medium-r-normal  — 10-100-75-75-c-60-iso8859-l 
-schumacher-clean-medium-r-normal  — 10-100-75-75-c-70-iso8859-l 
-schumacher-clean-medium-r-normal— 10-100-75-75-c-80-iso8859-l 
-schumacher-clean-medium-r-normal  — 12-  120-75-75-c-60-iso8859- 1 
-schumacher-clean-medium-r-normal  — 12-120-75-75-c-70-iso8859- 1 
-schumacher-clean-medium-r-normal  — 12-120-75-75-c-80-iso8859-l 
-schumacher-clean-medium-r-normal  — 1 3-  130-75-75-c-60-iso8859- 1 
-schumacher-clean-medium-r-normal  — 13-130-75-75-c-80-iso8859-l 
-schumacher-clean-medium-r-normal  — 14-140-75-75-c-70-iso8859-l 
-schumacher-clean-medium-r-normal  — 14-  140-75-75-c-80-iso8859- 1 
-schumacher-clean-medium-r-normal  -15-1 50-75-75-c-90-iso8859- 1 
-schumacher-clean-medium-r-normal  — 16-160-75-75-c-80-iso8859-l 
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Table  E-1.  Fonts  in  the  misc  Directory,  Release  4 (continued) 


Filename 


Font  name 


clR4x6.snf 

clR5x6.snf 

clR6x6.snf 

clR5x8.snf 

clR6x8.snf 

clR7x8.snf 

clR8x8.snf 

8xl6.snf 

8xl6rk.snf 

12x24.snf 

12x24rk.snf 

olcursor.snf 

olgllO.snf 

olgll2.snf 

olgll4.snf 

olgll9.snf 

cursor.snf 

deccurs.snf 

decsess.snf 

nil2.snf 


-schumacher-clean-medium-r-normal  — 6-60-75-75-c-40-iso8859-l 
-schumacher-clean-medium-r-normal  — 6-60-75-75-c-50-iso8859- 1 
-schumacher-clean-medium-r-normal  — 6-60-75-75-c-60-iso8859-l 
-schumacher-clean-medium-r-normal  — 8-80-75-75-c-50-iso8859-l 
-schumacher-clean-medium-r-normal  — 8-80-75-75-c-60-iso8859-l 
-schumacher-clean-medium-r-normal  — 8-80-75-75-c-70-iso8859- 1 
-schumacher-clean-medium-r-normal  — 8-80-75-75-c-80-iso8859-l 
-sony-fixed-medium-r-normal — 16-120-100-100-c-80-iso8859-l 
-sony-fixed-medium-r-normal — 16-120-1 00- 100-c-80-jisx0201 . 1976-0 
-sony-fixed-medium-r-normal  — 24-170-1 00- 1 00-c- 1 20-iso8859- 1 
-sony-fixed-medium-r-normal  — 24- 170-100-1 00-c- 1 20-jisx020 1 . 1 976-0 

-sun-open  look  cursor 12-120-75-75-p-160-sunolcursor-l 

-sun-open  look  glyph 10-100-75-75-p-101-sunolglyph-l 

-sun-open  look  glyph 12-120-75-75-p-113-sunolglyph-l 

-sun-open  look  glyph 14-140-75-75-p-128-sunolglyph-l 

-sun-open  look  glyph 19-190-75-75-p-154-sunolglyph-l 

cursor 

decwScursor 

decwSsession 

nil2 


Table  E-2.  Fonts  in  the  75dpi  Directory,  Release  4 


Filename 


Font  name 


courBOlO.snf 

courB012.snf 

courB014.snf 

courB018.snf 

courB024.snf 

courBO08.snf 

courBlO.snf 

courB12.snf 

courB  14.snf 

courB18.snf 

courB24.snf 

courB08.snf 

courOlO.snf 

cour012.snf 

cour014.snf 

cour018.snf 

cour024.snf 


-adobe-courier-bold-o-normal  — 10-100-75-75-m-60-iso8859-l 
-adobe-courier-bold-o-normal  — 12-120-75-75-m-70-iso8859-l 
-adobe-couricr-bold-o-normal  — 14-140-75-75-m-90-iso8859-l 
-adobe-courier-bold-o-normal  — 18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-bold-o-normal  — 24-240-75-75-m-150-iso8859-l 
-adobe-courier-bold-o-normal  — 8-80-75-75-m-50-iso8859- 1 
-adobe-courier-bold-r-normal  — 10-100-75-75-m-60-iso8859-l 
-adobe-courier-bold-r-normal  — 12-1 20-7 5 -7 5 -m-70-iso88 59- 1 
-adobe-courier-bold-r-normal  — 14-140-75-75-m-90-iso8859-l 
-adobe-courier-bold-r-normal  — 18-180-75-75-m-110-iso8859-l 
-adobe-courier-bold-r-normal  — 24-240-75-75-m-150-iso8859-l 
-adobe-courier-bold-r-normal  — 8-80-75-75-m-50-iso8859-l 
-adobe-courier-medium-o-normal  — 10-100-75-75-m-60-iso8859-l 
-adobe-courier-medium -o-normal  — 12-120-75-75-m-70-iso8859-l 
-adobe-courier-medium-o-normal  — 14-140-75-75-m-90-iso8859-l 
-adobe-courier-medium-o-normal  — 18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-medium-o-normal — 24-240-75-75-m-150-iso8859-l 
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Table  E-2.  Fonts  in  the  75dpi  Directory,  Release  4 (continued) 


Filename 


Font  name 


courO08.snf 

courRlO.snf 

courR12.snf 

courR14.snf 

courR18.snf 

courR24.snf 

courR08.snf 

helvBOlO.snf 

helvB012.snf 

helvB014.snf 

helvB018.snf 

helvB024.snf 

helvBO08.snf 

helvBlO.snf 

helvB12.snf 

helvB  14.snf 

helvB18.snf 

helvB24.snf 

helvB08.snf 

helvOlO.snf 

helv012.snf 

helv014.snf 

helv018.snf 

helv024.snf 

helvO08.snf 

helvRIO.snf 

helvR12.snf 

helvR14.snf 

helvR18.snf 

helvR24.snf 

helvR08.snf 

ncenBUO.snf 

ncenBI12.snf 

ncenBI14.snf 

ncenBI18.snf 

ncenBI24.snf 

ncenBI08.snf 

ncenBlO.snf 

ncenB12.snf 

ncenB14.snf 

ncenB18.snf 

ncenB24.snf 

ncenB08.snf 

ncenllO.snf 


-adobe-courier-medium -o-normal — 8-80-75-75-m-50-iso8859-l 
-adobe-courier-medium-r-normal — 10-100-75-75-m-60-iso8859-l 
-adobe-courier-medium -r-normal  — 12-120-75-75-m-70-iso8859-l 
-adobe-courier-medium-r-normal  — 14-140-75-75-m-90-iso8859-l 
-adobe-courier-medium-r-normal  — 18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-medium-r-normal — 24-240-75-75-m-150-iso8859-l 
-adobe-courier-medium-r-normal — 8-80-75-75-m-50-iso8859-l 
-adobe-helvetica-bold-o-normal  — 10-100-75-75-p-60-iso8859-l 
-adobe-hel  vetica-bold-o-normal  — 12-1 20-7 5 -75-p-69-iso8859- 1 
-adobe-helvetica-bold-o-normal  — 14-140-75-75-p-82-iso8859-l 
-adobe-helvetica-bold-o-normal  — 18-1 80-75-75-p- 1 04-iso8859- 1 
-adobe-helvetica-bold-o-normal  — 24-240-75-75-p-138-iso8859-l 
-adobe-helvetica-bold-o-normal  — 8-80-75-75-p-50-iso8859-l 
-adobe-helvetica-bold-r-normal  — 10-100-75-75-p-60-iso8859-l 
-adobe-helvetica-bold-r-normal  — 12-120-75-75-p-70-iso8859-l 
-adobe-helvetica-bold-r-normal  — 14-140-75-75-p-82-iso8859-l 
-adobe-helvetica-bold-r-normal  — 1 8-  180-75-75-p- 1 03-iso8859- 1 
-adobe-helvetica-bold-r-normal  — 24-240-75-75-p-138-iso8859-l 
-adobe-helvetica-bold-r-normal  — 8-80-75-75-p-50-iso8859-l 
-adobe-helvetica-medium-o-normal  — 10-100-75-75-p-57-iso8859-l 
-adobe-helvetica-medium-o-normal — 12-120-75-75-p-67-iso8859-l 
-adobe-helvetica-medium-o-normal  — 14-140-75-75-p-78-iso8859-l 
-adobe-helvetica-medium-o-normal  — 18-180-75-75-p-98-iso8859-l 
-adobe-helvetica-medium-o-normal  — 24-240-75-75-p- 1 30-iso8859- 1 
-adobe-helvetica-medium-o-normal  — 8-80-75-75-p-47-iso8859-l 
-adobe-helvetica-medium-r-normal  — 10-100-75-75-p-56-iso8859-l 
-adobe-helvetica-medium-r-normal  — 12- 120-75-75-p-67-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 14-  140-75-75-p-77-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 18-180-75-75-p-98-iso8859-l 
-adobe-helvetica-medium-r-normal  —24-240-75-75-p- 1 30-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 8-80-75-75-p-46-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 10-100-75-75-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal— 12-  120-75-75-p-76-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal  — 14- 140-75-75-p-88-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal  — 18-1 80-75-75-p-l  11 -iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal— 24-240-75-75-p- 148-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal— 8-80-75-75-p-56-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal — 10-100-75-75-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal  — 12-  120-75-75-p-77-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal  — 14-  140-75-75-p-87-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal  — 18- 180-75-75-p- 11 3-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal— 24-240-75-75-p- 149-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal— 8-80-75-75-p-56-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal  — 10-100-75-75-p-60-iso8859-l 
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Filename 
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ncenI12.snf 

ncenI14.snf 

ncenI18.snf 

ncenI24.snf 

ncenlOS.snf 

ncenRIO.snf 

ncenR12.snf 

ncenR14.snf 

ncenR18.snf 

ncenR24.snf 

ncenR08.snf 

symblO.snf 

symbl2.snf 

symbl4.snf 

symbl8.snf 

symb24.snf 

symb08.snf 

timBIlO.snf 

timBI12.snf 

timBI14.snf 

timBI18.snf 

timBI24.snf 

timBI08.snf 

timBlO.snf 

timB12.snf 

timB14.snf 

timB18.snf 

timB24.snf 

timB08.snf 

timllO.snf 

timI12.snf 

timI14.snf 

timI18.snf 

timI24.snf 

timI08.snf 

timRIO.snf 

timR12.snf 

timR14.snf 

timR18.snf 

timR24.snf 

timR08.snf 

luBISlO.snf 

luBIS12.snf 

luBIS14.snf 


-adobe-new  century  schoolbook-medium-i-normal  — 12-120-75-75-p-70-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal  — 14-140-75-75-p-81-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 18-180-75-75-p-104-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 24-240-75-75-p-136-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 8-80-75-75-p-50-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal — 10-100-75-75-p-60-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal  — 12-120-75-75-p-70-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal  — 14-  140-75-75-p-82-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal — 1 8-  180-75-75-p- 1 03-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal  — 24-240-75-75-p- 1 37-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal — 8-80-75-75-p-50-iso8859-l 
-adobe-symbol-medium-r-normal  — 10-100-75-75-p-61-adobe-fontspecific 
-adobe-symbol-medium-r-normal — 12-120-75-75-p-74-adobe-fontspecific 
-adobe-symbol-medium-r-normal  — 14-140-75-75-p-85-adobe-fontspecific 
-adobe-symbol-medium-r-normal — 18-180-75-75-p-107-adobe-fontspecific 
-adobe-symbol-medium-r-normal  — 24-240-75-75-p-  142-adobe-fontspecific 
-adobe-symbol-medium-r-normal — 8-80-75-75-p-51-adobc-fontspecific 
-adobe-times-bold-i-normal  — 10-100-75-75-p-57-iso8859-l 
-adobe-times-bold-i-normal  — 12-120-75-75-p-68-iso8859-l 
-adobe-times-bold-i-normal  — 14-140-75-75-p-77-iso8859-l 
-adobe-times-bold-i-normal  — 18-180-75-75-p-98-iso8859-l 
-adobe-times-bold-i-normal  — 24-240-75-75-p- 1 28-iso8859- 1 
-adobe-times-bold-i-normal — 8-80-75-75-p-47-iso8859-l 
-adobe-times-bold-r-normal  — 1 0-  100-75-75-p-57-iso8859- 1 
-adobe-times-bold-r-normal — 12-120-75-75-p-67-iso8859-l 
-adobe-times-bold-r-normal  — 14-  140-75-75-p-77-iso8859- 1 
-adobe-times-bold-r-normal — 1 8-  180-75-75-p-99-iso8859- 1 
-adobe-times-bold-r-normal — 24-240-75-75-p- 132-iso8859-l 
-adobe-times-bold-r-normal — 8-80-75-75-p-47-iso8859-l 
-adobe-times-medium-i-normal  — 10-100-75-75-p-52-iso8859-l 
-adobe-times-medium-i-normal  — 12-  120-75-75-p-63-iso8859- 1 
-adobe-times-medium-i-normal  — 14-140-75-75-p-73-iso8859-l 
-adobe-times-medium-i-normal  — 1 8-  180-75-75-p-94-iso8859- 1 
-adobe-times-medium-i-normal  — 24-240-75-75-p- 1 25-iso8859- 1 
-adobe-times-medium-i-normal — 8-80-75-75-p-42-iso8859-l 
-adobe-times-medium-r-normal — 10-  100-75-75-p-54-iso8859- 1 
-adobe-times-medium-r-normal  — 12-120-75-75-p-64-iso8859-l 
-adobe-times-medium-r-normal  — 14-  140-75-75-p-74-iso8859- 1 
-adobe-times-medium-r-normal  — 18-180-75-75-p-94-iso8859-l 
-adobe-times-medium-r-normal — 24-240-75-75-p- 124-iso8859-l 
-adobe-times-medium-r-normal — 8-80-75-75-p-44-iso8859-l 
-b&h-lucida-bold-i-normal-sans-10-100-75-75-p-67-iso8859-l 
-b&h-lucida-bold-i-normal-sans-12-120-75-75-p-79-iso8859-l 
-b&h-lucida-bold-i-normal-sans-14-140-75-75-p-92-iso8859-l 


Release  3 and  4 Standard  Fonts 


643 


Release  3 and  4 
Standard  Fonts 


Table  E-2.  Fonts  in  the  75dpi  Directory,  Release  4 (continued) 


Filename 
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luBIS18.snf 

luBIS19.snf 

luBIS24.snf 

luBIS08.snf 

luBSlO.snf 

luBS12.snf 

luBS14.snf 

luBS18.snf 

luBS19.snf 

luBS24.snf 

luBS08.snf 

luISlO.snf 

luIS12.snf 

luIS14.snf 

luIS18.snf 

luIS19.snf 

luIS24.snf 

luIS08.snf 

luRSlO.snf 

luRS12.snf 

luRS14.snf 

luRS18.snf 

luRS19.snf 

luRS24.snf 

luRS08.snf 

lubBUO.snf 

lubBI12.snf 

lubBI14.snf 

lubBI18.snf 

lubBI19.snf 

lubBI24.snf 

lubBI08.snf 

lubBlO.snf 

lubB12.snf 

lubB14.snf 

lubB18.snf 

lubB19.snf 

lubB24.snf 

lubB08.snf 

lubllO.snf 

lubI12.snf 

lubI14.snf 

lubI18.snf 

lubI19.snf 


-b&h-lucida-bold-i-normal-sans- 18-1 80-75-75-p- 1 1 9-iso8859- 1 
-b&h-lucida-bold-i-normal-sans-19-190-75-75-p-122-iso8859-l 
-b&h-lucida-bold-i-normal-sans-24-240-75-75-p-151-iso8859-l 
-b&h-lucida-bold-i-normal-sans-8-80-75-75-p-49-iso8859-l 
-b&h-lucida-bold-r-normal-sans-10-100-75-75-p-66-iso8859-l 
-b&h-lucida-bold-r-normal-sans-12-120-75-75-p-79-iso8859-l 
-b&h-lucida-bold-r-normal-sans-14-140-75-75-p-92-iso8859-l 
-b&h-lucida-bold-r-normal-sans- 18-1 80-75-75-p- 1 20-iso8859- 1 
-b&h-lucida-bold-r-normal-sans- 19- 190-75-75-p-122-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-24-240-75-75-p-152-iso8859-l 
-b&h-lucida-bold-r-normal-sans-8-80-75-75-p-50-iso8859-l 
-b&h-lucida-medium-i-normal-sans-10-100-75-75-p-59-iso8859-l 
-b&h-lucida-medium-i-normal-sans-12-120-75-75-p-71-iso8859-l 
-b&h-lucida-medium-i-normal-sans-14-140-75-75-p-82-iso8859-l 
-b&h-lucida-medium-i-normal-sans-18-180-75-75-p-105-iso8859-l 
-b&h-lucida-medium-i-normal-sans- 1 9-  190-75-75-p-  108-iso8859- 1 
-b&h-lucida-medium-i-normal-sans-24-240-75-75-p-136-iso8859-l 
-b&h-lucida-medium-i-normal-sans-8-80-75-75-p-45-iso8859-l 
-b&h-lucida-medium-r-normal-sans-10-100-75-75-p-58-iso8859-l 
-b&h-lucida-medium-r-normal-sans- 1 2- 1 20-75-75-p-7 1 -iso8859- 1 
-b&h-lucida-medium-r-normal-sans- 14-  140-75-75-p-8 1 -iso8859- 1 
-b&h-lucida-medium-r-normal-sans- 1 8- 1 80-75-75-p-  106-iso8859- 1 
-b&h-lucida-medium-r-normal-sans-19-190-75-75-p-108-iso8859-l 
-b&h-lucida-medium-r-normal-sans-24-240-75-75-p-136-iso8859-l 
-b&h-lucida-medium-r-normal-sans-8-80-75-75-p-45-iso8859-l 
-b&h-lucidabright-demibold-i-normal — 10-100-75-75-p-59-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 12-120-75-75-p-72-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 14-  140-75-75-p-84-iso8859- 1 
-b&h-lucidabright-demibold-i-normal  -18-1 80-75-75-p- 1 07-iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 19-  190-75-75-p- 1 14-iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 24-240-75-75-p-143-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 8-80-75-75-p-48-iso8859-l 
-b&h-lucidabright-demibold-r-normal  — 10-  100-75-75-p-59-iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 12-120-75-75-p-71-iso8859-l 
-b&h-lucidabright-demibold-r-normal  — 14-140-75-75-p-84-iso8859-l 
-b&h-lucidabright-demibold-r-normal  -18-1 80-75-75-p-  107-iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 1 9- 190-75-75-p- 1 14-iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 24-240-75-75-p-  143-iso8859- 1 
-b&h-lucidabright-demibold-r-normal — 8-80-75-75-p-47-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 10-100-75-75-p-57-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 12-120-75-75-p-67-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 14-  140-75-75-p-80-iso8859- 1 
-b&h-lucidabright-medium-i-normal  — 18-180-75-75-p-102-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 19-190-75-75-p-109-iso8859-l 
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lubI24.snf 

lubI08.snf 

lubRIO.snf 

lubR12.snf 

lubR14.snf 

lubR18.snf 

lubR19.snf 

lubR24.snf 

lubR08.snf 

lutBSlO.snf 

lutBS12.snf 

lutBS14.snf 

lutBS18.snf 

lutBS19.snf 

lutBS24.snf 

lutBS08.snf 

lutRSlO.snf 

lutRS12.snf 

lutRS14.snf 

lutRS18.snf 

lutRS19.snf 

lutRS24.snf 

lutRS08.snf 

charBUO.snf 

charBI12.snf 

charBI14.snf 

charBI18.snf 

charBI24.snf 

charBI08.snf 

charBlO.snf 

charB12.snf 

charB14.snf 

charB18.snf 

charB24.snf 

charB08.snf 

charllO.snf 

charI12.snf 

charl  14.  snf 

charI18.snf 

charI24.snf 

charI08.snf 

charRIO.snf 

charR12.snf 

charR14.snf 


-b&h-lucidabright-medium-i-normal  — 24-240-75-75-p-136-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 8-80-75-75-p-45-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 10-100-75-75-p-56-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 12-  120-75-75-p-68-iso8859- 1 
-b&h-lucidabright-medium-r-normal  — 14-140-75-75-p-80-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 18-1 80-75-75-p- 1 03-iso8859- 1 
-b&h-lucidabright-medium-r-normal  — 19-  190-75-75-p- 1 09-iso8859- 1 
-b&h-lucidabright-medium-r-normal — 24-240-75-75-p-137-iso8859-l 
-b&h-lucidabright-medium-r-normal — 8-80-75-75-p-45-iso8859-l 
-b&h-lucidatypewriter-bold-r-nonnal-sans- 1 0-  100-75-75-m-60-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans- 1 2-  120-75-75-m-70-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans- 14-  140-75-75-m-90-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans- 1 8-  180-75-75-m- 1 10-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans- 19- 190-75-75-m- 1 10-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans-24-240-75-75-m-140-iso8859-l 
-b&h-lucidatypewriter-bold-r-normal-sans-8-80-75-75-m-50-iso8859-l 
-b&h-lucidatypewriter-medium-r-normal-sans-10-100-75-75-m-60-iso8859-l 
-b&h-lucidatypewriter-medium-r-normal-sans-12-120-75-75-m-70-iso8859-l 
-b&h-lucidatypewriter-medium-r-normal-sans-14-140-75-75-m-90-iso8859-l 
-b&h-lucidatypewriter-medium-r-normal-sans-18-180-75-75-m-110-iso8859- 
-b&h-lucidatypewriter-medium-r-normal-sans-19-190-75-75-m-110-iso8859- 
-b&h-lucidatypewriter-medium-r-normal-sans-24-240-75-75-m-140-iso8859- 
-b&h-lucidatypewriter-medium-r-normal-sans-8-80-75-75-m-50-iso8859-l 
-bitstream -charter-bold-i-normal  — 10-100-75-75-p-62-iso8859-l 
-bitstream-charter-bold-i-normal  — 12-120-75-75-p-74-iso8859-l 
-bitstream-charter-bold-i-normal  — 15-140-75-75-p-93-iso8859-l 
-bitstream-charter-bold-i-normal  — 19-180-75-75-p-l  17-iso8859-l 
-bitstream-charter-bold-i-normal  — 25-240-75-75-p-154-iso8859-l 
-bitstream-charter-bold-i-normal  — 8-80-75-75-p-50-iso8859-l 
-bitstream-charter-bold-r-normal  — 10-100-75-75-p-63-iso8859-l 
-bitstream-charter-bold-r- normal  — 12-  120-75-75-p-75-iso8859- 1 
-bitstream-charter-bold-r-normal  — 1 5-  140-75-75-p-94-iso8859- 1 
-bitstream-charter-bold-r-normal  — 19-180-75-75-p-l  19-iso8859-l 
-bitstream-charter-bold-r-normal — 25-240-75-75-p-157-iso8859-l 
-bitstream-charter-bold-r-normal  — 8-80-75-75-p-50-iso8859-l 
-bitstream-charter-medium-i-normal  — 10-100-75-75-p-55-iso8859-l 
-bitstream-charter-medium-i-normal  — 12-120-75-75-p-65-iso8859-l 
-bitstream-charter-medium-i-normal  — 15-140-75-75-p-82-iso8859-l 
-bitstream-charter-medium-i-normal  — 19-180-75-75-p-103-iso8859-l 
-bitstream -charter-medium-i-normal  — 25-240-75-75-p- 1 36-iso8859- 1 
-bitstream-charter-medium-i-normal  — 8-80-75-75-p-44-iso8859- 1 
-bitstream-charter-medium-r-normal  — 10-100-75-75-p-56-iso8859-l 
-bitstream-charter-medium-r-normal  — 12-120-75-75-p-67-iso8859-l 
-bitstream-charter-medium-r-normal  — 15-140-75-75-p-84-iso8859-l 
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charR18.snf 

charR24.snf 

charR08.snf 

techB14.snf 

termB14.snf 

techl4.snf 

terml4.snf 

-bitstream-charter-medium-r-normal  — 19-180-75-75-p-106-iso8859-l 
-bitstream-charter-medium-r-normal  — 25 -240-75 -75 -p- 1 39-iso8859- 1 
-bitstream-charter-medium-r-normal  — 8-80-75-75-p-45-iso8859-l 
-dec-terminal-bold-r-normal  — 14-140-75-75-c-80-dec-dectech 
-dec-terminal-bold-r-normal  — 14-140-75-75-c-80-iso8859-l 
-dec-terminal-medium-r-normal  — 14-140-75-75-c-80-dec-dectech 
-dec-terminal-medium-r-normal — 14-140-75-75-c-80-iso8859-l 
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Filename 
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courBO08.snf 

courBOlO.snf 

courB012.snf 

courB014.snf 

courB018.snf 

courB024.snf 

courB08.snf 

courBlO.snf 

courB12.snf 

courB14.snf 

courB18.snf 

courB24.snf 

courO08.snf 

courOlO.snf 

cour012.snf 

cour014.snf 

cour018.snf 

cour024.snf 

courR08.snf 

courRIO.snf 

courR12.snf 

courR14.snf 

courR18.snf 

courR24.snf 

helvBO08.snf 

helvBOlO.snf 

helvB012.snf 

helvB014.snf 

helvB018.snf 

helvB024.snf 

-adobe-courier-bold-o-normal  — 1 1-80- 100-1 00-m-60-iso8859-l 
-adobe-courier-bold-o-normal  — 14-100-100-1 00-m-90-iso8859- 1 
-adobe-courier-bold-o-normal  — 1 7- 120- 1 00- 1 00-m- 1 00-iso8859- 1 
-adobe-courier-bold-o-normal  — 20- 140- 1 00- 1 00-m- 1 1 0-iso8859- 1 
-adobe-courier-bold-o-normal  — 25-1 80- 100-1 00-m- 1 50-iso8859- 1 
-adobe-courier-bold-o-normal — 34-240-1 00- 100-m-200-iso8859-l 
-adobe-courier-bold-r-normal  — 11-80-100-1 00-m-60-iso8859 - 1 
-adobe-courier-bold-r-normal  — 14-100-100-1 00-m-90-iso8859- 1 
-adobe-courier-bold-r-normal  — 17-120-100-1 00-m-  100-iso8859- 1 
-adobe-courier-bold-r-normal  — 20- 140-100-1 00-m- 1 10-iso8859- 1 
-adobe-courier-bold-r-normal  — 25- 180- 1 00- 1 00-m- 1 50-iso8859- 1 
-adobe-courier-bold-r-normal — 34-240-1 00-  100-m-200-iso8859-l 
-adobe-courier-medium-o-normal  — 1 1-80- 100-1 00-m-60-iso8859-l 
-adobe-courier-medium -o-normal  — 14-100-100-1 00-m-90-iso8859- 1 
-adobe-courier-medium-o-normal  — 17- 120- 100-  100-m-  100-iso8859- 1 
-adobe-courier-medium-o-normal — 20- 140- 100-1 00-m- 110-iso8859-l 
-adobe-courier-medium-o-normal  — 25-1 80-100-1 00-m- 1 50-iso8859- 1 
-adobe-courier-medium-o-normal — 34-240-100-100-m-200-iso8859-l 
-adobe-courier-medium -r-normal  — 1 1-80- 100-1 00-m-60-iso8859-l 
-adobe-courier-medium -r-normal  — 14-100-100-100-m-90-iso8859-l 
-adobe-courier-medium -r-normal  -17-120-100-1 00-m- 1 00-iso8859- 1 
-adobe-courier-medium -r-normal  — 20- 140- 100-1 00-m- 1 10-iso8859-l 
-adobe-courier-medium-r-normal  -25-180- 1 00- 1 00-m- 1 50-iso8859- 1 
-adobe-courier-medium -r-normal — 34-240-100-100-m-200-iso8859-l 
-adobe-helvetica-bold-o-normal  — 1 1-80-1 00-1 00-p-60-iso8859-l 
-adobe-helvetica-bold-o-normal  — 14- 100- 100- 100-p-82-iso8859- 1 
-adobe-helvetica-bold-o-normal  -17-120-1 00-  100-p-92-iso8859- 1 
-adobe-helvetica-bold-o-normal  -20- 140- 100-  100-p-  103-iso8859- 1 
-adobe-helvetica-bold-o-normal  -25- 1 80- 1 00- 1 00-p- 1 38-iso8859- 1 
-adobe-helvetica-bold-o-normal -34-240- 100- 100-p- 182-iso8859- 1 
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helvB08.snf 

helvBlO.snf 

helvB12.snf 

helvB14.snf 

helvB18.snf 

helvB24.snf 

helvO08.snf 

helvOlO.snf 

helv012.snf 

helv014.snf 

helv018.snf 

helv024.snf 

helvR08.snf 

helvRIO.snf 

helvR12.snf 

helvR14.snf 

helvR18.snf 

helvR24.snf 

ncenBI08.snf 

ncenBUO.snf 

ncenBI12.snf 

ncenBI14.snf 

ncenBI18.snf 

ncenBI24.snf 

ncenB08.snf 

ncenBlO.snf 

ncenB12.snf 

ncenB14.snf 

ncenB18.snf 

ncenB24.snf 

ncenI08.snf 

ncenllO.snf 

ncenI12.snf 

ncenI14.snf 

ncenI18.snf 

ncenI24.snf 

ncenR08.snf 

ncenRIO.snf 

ncenR12.snf 

ncenR14.snf 

ncenR18.snf 

ncenR24.snf 

symb08.snf 

symblO.snf 


Font  name 

-adobe-helvetica-bold-r-normal  — 1 1-80- 100-1 00-p-60-iso8859-l 
-adobe-helvetica-bold-r-normal  — 14- 100-100-  100-p-82-iso8859- 1 
-adobe-helvetica-bold-r-normal  — 17-120-100-1 00-p-92-iso8859- 1 
-adobe-helvetica-bold-r-normal  — 20- 140- 100-1 00-p- 1 05-iso8859- 1 
-adobe-helvetica-bold-r-normal  — 25-180-100-1 00-p- 1 38-iso8859- 1 
-adobe-helvetica-bold-r-normal  — 34-240-100-1 00-p- 1 82-iso8859- 1 
-adobe-helvetica-medium-o-normal  — 1 l-80-100-100-p-57-iso8859-l 
-adobe-helvetica-medium-o-normal  — 14-100-100-1 00-p-78-iso8859- 1 
-adobe-helvetica-medium-o-normal  — 17-120-100-1 00-p-88-iso8859- 1 
-adobe-helvetica-medium-o-normal  — 20-140-100-100-p-98-iso8859-l 
-adobe-helvetica-medium-o-normal  — 25-180-100- 1 00-p- 1 30-iso8859- 1 
-adobe-helvetica-medium-o-normal  — 34-240-100- 1 00-p- 1 76-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 1 1-80- 100-1 00-p-56-iso8859-l 
-adobe-helvetica-medium-r-normal  — 14-100-100-1 00-p-76-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 17-120-100-100-p-88-iso8859-l 
-adobe-helvetica-medium-r-normal  — 20- 140- 1 00-  100-p- 1 00-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 25-1 80-100- 1 00-p- 1 30-iso8859- 1 
-adobe-helvetica-medium-r-normal  — 34-240-100- 1 00-p- 1 76-iso8859- 1 
-adobe-new  century  schoolbook-bold-i-normal  — ll-80-100-100-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 14-100-100-100-p-88-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 17-120-100-100-p-99-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 20- 140- 100-  100-p- lll-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 25-180-100-100-p-148-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal — 34-240-100-100-p-193-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal  — ll-80-100-100-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal — 14-100-100-100-p-87-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal  — 17-120-100-100-p-99-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal — 20- 140- 100-1 00-p- 1 13-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal — 25-180-100-100-p-149-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal — 34-240- 100-1 00-p- 193-iso8859-l 
-adobe-new  century  schoolbook-medium -i-normal  — ll-80-100-100-p-60-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal  — 14-100-100-100-p-81-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal  — 17-120-100-100-p-92-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 20-140-100-100-p-104-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 25-180-100-100-p-136-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal — 34-240- 100-1 00-p-  182-iso8859-l 
-adobe-new  century  schoolbook-medium -r-normal  — ll-80-100-100-p-60-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal — 14- 100- 100-  100-p-82-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal  — 17-120-100-100-p-91-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal  — 20- 140- 100-  100-p- 1 03-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal  — 25-180- 1 00- 1 00-p- 1 36-iso8859- 1 
-adobe-new  century  schoolbook-medium-r-normal — 34-240-100- 1 00-p- 1 8 1 -iso8859- 1 
-adobe-symbol-medium-r-normal  — 11  -80- 1 00- 1 00-p-61  -adobe-fontspecific 
-adobe-symbol-medium-r-normal  — 14-100-100-100-p-85-adobe-fontspecific 
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Filename 

Font  name 

symbl2.snf 

symbl4.snf 

symbl8.snf 

symb24.snf 

timBI08.snf 

timBHO.snf 

timBI12.snf 

timBI14.snf 

timBI18.snf 

timBI24.snf 

timB08.snf 

timBlO.snf 

timB12.snf 

timB14.snf 

timB18.snf 

timB24.snf 

timI08.snf 

timllO.snf 

timI12.snf 

timI14.snf 

timI18.snf 

timI24.snf 

timR08.snf 

timRIO.snf 

timR12.snf 

timR14.snf 

timR18.snf 

timR24.snf 

luBIS08.snf 

luBISlO.snf 

luBIS12.snf 

luBIS14.snf 

luBIS18.snf 

luBIS19.snf 

luBIS24.snf 

luBS08.snf 

luBSlO.snf 

luBS12.snf 

luBS14.snf 

luBS18.snf 

luBS19.snf 

luBS24.snf 

luIS08.snf 

luISlO.snf 

-adobe-sy  mbol-medium-r-normal  — 17-1 20- 1 00- 1 00-p-95-adobe-fontspecific 
-adobe-symbol-medium-r-normal  — 20-140- 100-  100-p-  107-adobe-fontspecific 
-adobe-symbol-medium-r-normal  — 25-180- 1 00- 1 00-p-  142-adobe-fontspecific 
-adobe-symbol-medium-r-normal — 34-240-100-100-p-191-adobe-fontspecific 
-adobe-times-bold-i-normal — 1 l-80-100-100-p-57-iso8859-l 
-adobe-times-bold-i-normal  — 14- 100- 100-  100-p-77-iso8859- 1 
-adobe-times-bold-i-normal — 17-120-100-1 00-p-86-iso8859- 1 
-adobe-times-bold-i-normal  — 20- 140- 100-  100-p-98-iso8859- 1 
-adobe-times-bold-i-normal  — 25- 180- 100-  100-p-  128-iso8859- 1 
-adobe-times-bold-i-normal  — 34-240- 1 00- 1 00-p- 1 70-iso8859- 1 
-adobe-times-bold-r-normal  — 11-80-100-1 00-p-57-iso8859- 1 
-adobe-times-bold-r-normal  — 14-100-100-1 00-p-76-iso8859- 1 
-adobe-times-bold-r-normal  — 17- 120- 100-  100-p-88-iso8859-l 
-adobe-times-bold-r-normal  — 20- 140- 100-  100-p-  100-iso8859- 1 
-adobe-times-bold-r-normal  — 25- 180- 100-  100-p- 1 32-iso8859- 1 
-adobe-times-bold-r-normal — 34-240- 100-1 00-p- 177-iso8859-l 
-adobe-  times-medium-i-normal — 11-80-100-1 00-p-52-iso8859- 1 
-adobe-times-medium-i-normal  — 14-100-100-100-p-73-iso8859-l 
-adobe-times -medium-i-normal  — 17-120-100-1 00-p-84-iso8859- 1 
-adobe-times-medium-i-normal  — 20- 140- 1 00-  100-p-94-iso8859- 1 
-adobe-times-medium-i-normal  — 25-180-1 00-  100-p- 1 25-iso8859- 1 
-adobe-times-medium-i-normal — 34-240- 100-1 00-p- 168-iso8859-l 
-adobe- times-medium-r-normal  -11-80-1 00- 100-p-54-iso8859- 1 
-adobe-times-medium-r-normal  — 14-100-1 00-  100-p-74-iso8859- 1 
-adobe- times-medium-r-normal  -17-120-1 00-  100-p-84-iso8859- 1 
-adobe-times-medium-r-normal  -20- 140- 100- 100-p-96-iso8859- 1 
-adobe-times-medium-r-normal  -25-180-100-1 00-p-  125-iso8859- 1 
-adobe-times-medium-r-normal — 34-240- 1 00-  100-p- 1 70-iso8859- 1 
-b&h-lucida-bold-i-normal-sans- 11-80-100-1 00-p-69-iso8859- 1 
-b&h-lucida-bold-i-normal-sans- 14-100-100-1 00-p-90-iso8859- 1 
-b&h-lucida-bold-i-normal-sans- 17-120-1 00-  100-p- 1 08-iso8859- 1 
-b&h-lucida-bold-i-normal-sans-20- 140-100-  100-p- 1 27-iso8859- 1 
-b&h-lucida-bold-i-normal-sans-25- 1 80- 1 00-  100-p- 1 59-iso8859- 1 
-b&h-lucida-bold-i-normal-sans-26- 190- 100- 1 00-p- 1 66-iso8859- 1 
-b&h-lucida-bold-i-normal-sans-34-240-100-100-p-215-iso8859-l 
-b&h-lucida-bold-r-normal-sans- 1 1-80-100-1 00-p-70-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-14-100-100-100-p-89-iso8859-l 
-b&h-lucida-bold-r-normal-sans- 1 7-120-100- 1 00-p- 1 08-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-20- 140- 1 00- 1 00-p- 1 27-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-25- 1 80-100- 1 00-p- 1 58-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-26- 190- 1 00- 1 00-p- 1 66-iso8859- 1 
-b&h-lucida-bold-r-normal-sans-34-240- 100-1 00-p-2 1 6-iso8859- 1 
-b&h-lucida-medium-i-normal-sans-ll-80-100-100-p-62-iso8859-l 
-b&h-lucida-medium-i-normal-sans- 14-100-1 00-  100-p-80-iso8859- 1 
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luIS12.snf 

luIS14.snf 

luIS18.snf 

luIS19.snf 

luIS24.snf 

luRS08.snf 

luRSlO.snf 

luRS12.snf 

luRS14.snf 

luRS18.snf 

luRS19.snf 

luRS24.snf 

lubBI08.snf 

lubBUO.snf 

lubBI12.snf 

lubBI14.snf 

lubBI18.snf 

lubBI19.snf 

lubBI24.snf 

lubB08.snf 

lubBlO.snf 

lubB12.snf 

lubB14.snf 

lubB18.snf 

lubB19.snf 

lubB24.snf 

lubI08.snf 

lubllO.snf 

lubI12.snf 

lubI14.snf 

lubI18.snf 

lubI19.snf 

lubI24.snf 

lubR08.snf 

lubRIO.snf 

lubR12.snf 

lubR14.snf 

lubR18.snf 

lubR19.snf 

lubR24.snf 

lutBS08.snf 

lutBSlO.snf 

lutBS12.snf 

lutBS14.snf 


-b&h-lucida-medium-i-normal-sans- 17-120-100-1 00-p-97-iso8859- 1 
-b&h-lucida-medium-i-normal-sans-20- 140- 1 00- 1 00-p- 1 14-iso8859- 1 
-b&h-lucida-medium-i-normal-sans-25- 180- 1 00- 1 00-p- 141  -iso8859- 1 
-b&h-lucida-medium-i-normal-sans-26-190-100-100-p-147-iso8859-l 
-b&h-lucida-medium-i-normal-sans-34-240- 100-1 00-p-  192-iso8859- 1 
-b&h-lucida-medium-r-normal-sans- 11-80-100-1 00-p-63-iso8859- 1 
-b&h-lucida-medium-r-normal-sans- 14-100-1 00- 1 00-p-80-iso8859- 1 
-b&h-lucida-medium-r-normal-sans- 17-120-1 00- 100-p-96-iso8859- 1 
-b&h-lucida-medium-r-normal-sans-20- 140- 100-  100-p- 1 14-iso8859- 1 
-b&h-lucida-medium-r-normal-sans-25- 1 80- 1 00-  100-p-  142-iso8859- 1 
-b&h-lucida-medium-r-normal-sans-26- 1 90- 100-  100-p-  147-iso8859- 1 
-b&h-lucida-medium-r-normal-sans-34-240- 1 00-  100-p- 19 1 -iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 1 l-80-100-100-p-66-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 14-100-1 00-  100-p-84-iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 17- 120- 100-  100-p- 1 0 1 -iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 20- 140- 100-1 00-p- 1 19-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 25-180-100-100-p-149-iso8859-l 
-b&h-lucidabright-demibold-i-normal  — 26-190- 100-1 00-p- 1 56-iso8859- 1 
-b&h-lucidabright-demibold-i-normal  — 34-240-100-100-p-203-iso8859-l 
-b&h-lucidabright-demibold-r-normal  — 1 l-80-100-100-p-66-iso8859-l 
-b&h-lucidabright-demibold-r-normal  — 14-100-100-1 00-p-84-iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 1 7- 120- 100-  100-p- 101  -iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 20- 140- 100-1 00-p- 1 18-iso8859-l 
-b&h-lucidabright-demibold-r-normal  — 25- 180-100-1 00-p-  149-iso8859- 1 
-b&h-lucidabright-demibold-r-normal  — 26- 190- 100-  100-p- 1 55-iso8859- 1 
-b&h-lucidabright-demibold-r-normal — 34-240-100-100-p-202-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 1 1-80- 100-1 00-p-63-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 14-100-100-100-p-80-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 17-120-100-1 00-p-96-iso8859- 1 
-b&h-lucidabright-medium-i-normal  — 20- 140- 100-1 00-p- 1 13-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 25-180-100-1 00-p-  142-iso8859- 1 
-b&h-lucidabright-medium-i-normal  — 26- 190- 100-1 00-p-  148-iso8859-l 
-b&h-lucidabright-medium-i-normal  — 34-240- 1 00-  100-p-  194-iso8859- 1 
-b&h-lucidabright-medium-r-normal — 1 1-80- 100-1 00-p-63-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 14-100-100-100-p-80-iso8859-l 
-b&h-lucidabright-medium-r-normal — 17-120-100-100-p-96-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 20- 140- 100-1 00-p- 1 14-iso8859-l 
-b&h-lucidabright-medium-r-normal  — 25- 1 80- 100-1 00-p- 1 42-iso8859- 1 
-b&h-lucidabright-medium-r-normal  — 26-190-100-100-p-149-iso8859-l 
-b&h-lucidabright-medium-r-normal — 34-240-100-100-p-193-iso8859-l 
-b&h-lucidatypewriter-bold-r-normal-sans- 11-80-100-1 00-m-70-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans- 14- 100- 100- 100-m-80-iso8859-l 
-b&h-lucidatypewriter-bold-r-normal-sans- 1 7- 120- 100-  100-m-  100-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans-20- 140- 1 00- 1 00-m- 1 20-iso8859- 1 
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lutBS18.snf 

lutBS19.snf 

lutBS24.snf 

lutRS08.snf 

lutRSlO.snf 

lutRS12.snf 

lutRS14.snf 

lutRS18.snf 

lutRS19.snf 

lutRS24.snf 

charBI08.snf 

charBUO.snf 

charBI12.snf 

charBI14.snf 

charBI18.snf 

charBI24.snf 

charB08.snf 

charBlO.snf 

charB12.snf 

charB14.snf 

charB18.snf 

charB24.snf 

charI08.snf 

charllO.snf 

charI12.snf 

charI14.snf 

charI18.snf 

charI24.snf 

charR08.snf 

charRIO.snf 

charR12.snf 

charR14.snf 

charR18.snf 

charR24.snf 

techB14.snf 

termB14.snf 

techl4.snf 

terml4.snf 


Font  name 

-b&h-lucidatypewriter-bold-r-normal-sans-25- 180- 100- 1 00-m- 1 50-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans-26- 190- 1 00- 1 00-m- 1 59-iso8859- 1 
-b&h-lucidatypewriter-bold-r-normal-sans-34-240- 1 00- 1 00-m-200-iso8859- 1 
-b&h-lucidatypewriter-medium-r-normal-sans- 1 1 -80- 100-1 00-m-70-iso8859- 1 
-b&h-lucidatypewriter-medium-r-normal-sans- 14- 100- 1 00- 1 00-m-80-iso8859- 1 
-b&h-lucidatypewriter-medium-r-normal-sans- 17- 120-100- 100-m-100-iso8859- 1 
-b&h-lucidatypewriter-medium-r-normal-sans-20-140-100-100-m-120-iso8859-l 
-b&h-lucidatypewriter-medium-r-normal-sans-25-180-100-100-m-150-iso8859-l 
-b&h-lucidatypewri  ter-medium-r-normal-sans-26- 1 90- 1 00- 1 00-m- 1 59-iso8859- 1 
-b&h-lucidatypewriter-medium-r-normal-sans-34-240-100-100-m-200-iso8859-l 
-bitstream-charter-bold-i-normal  — 1 l-80-100-100-p-68-iso8859-l 
-bitstream-charter-bold-i-normal  — 14-100-100-100-p-86-iso8859-l 
-bitstream-charter-bold-i-normal  — 17-120-100-1 00-p- 1 05-iso8859- 1 
-bitstream-charter-bold-i-normal  — 19-140-100-1 00-p- 1 1 7-iso8859- 1 
-bitstream-charter-bold-i-normal  — 25-180-100-1 00-p- 1 54-iso8859- 1 
-bitstream-charter-bold-i-normal  — 33-240-100-1 00-p-203-iso8859- 1 
-bitstream-charter-bold-r-normal  — 1 1-80- 100-1 00-p-69-iso8859-l 
-bitstream-charter-bold-r-normal  — 14- 100- 100-1 00-p-88-iso8859- 1 
-bitstream-charter-bold-r-normal  — 17-120-100-1 00-p- 1 07-iso8859- 1 
-bitstream-charter-bold-r-normal  -19-140-100-1 00-p- 1 1 9-iso8859- 1 
-bitstream -charter-bold-r-normal  -25- 180-100-1 00-p- 1 57-iso8859- 1 
-bitstream-charter-bold-r-normal  -33-240-100-1 00-p-206-iso8859- 1 
-bitstream-charter-medium-i-normal  — 1 1-80- 100-1 00-p-60-iso8859-l 
-bitstream-charter-medium-i-normal  — 14- 100- 100-  100-p-76-iso8859- 1 
-bitstream-charter-medium-i-normal  -17-120-100-1 00-p-92-iso8859- 1 
-bitstream-charter-medium-i-normal  — 1 9- 140- 1 00- 1 00-p- 1 03  -iso8859- 1 
-bitstream-charter-medium-i-normal  -25- 180-100-1 00-p- 1 36-iso8859- 1 
-bitstream-charter-medium-i-normal  -33-240-100-1 00-p- 1 79-iso8859- 1 
-bitstream-charter-medium-r-normal  — 1 l-80-100-100-p-61-iso8859-l 
-bitstream-charter-medium-r-normal  — 14-100- 100- 100-p-78-iso8859- 1 
-bitstream-charter-medium-r-normal  -17-120-100-1 00-p-95-iso8859- 1 
-bitstream-charter-medium-r-normal  -19-140-100-1 00-p- 1 06-iso8859- 1 
-bitstream-charter-medium-r-normal  -25-180-100-1 00-p- 1 39-iso8859- 1 
-bitstream-charter-medium-r-normal -33-240- 1 00- 100-p- 1 83-iso8859- 1 
-bitstream-terminal-bold-r-normal  -18- 140- 100-1 00-c-l  10-dec-dectech 
-bitstream-terminal-bold-r-normal  — 18- 140- 1 00- 1 00-c- 1 1 0-iso8859- 1 
-bitstream-terminal-medium-r-normal  — 18- 140- 100- 1 00-c-l  10-dec-dectech 
-bitstream-terminal-medium-r-normal  -18-140-100-1 00-c- 1 10-iso8859- 1 
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6x10 

6x12 

8x13 

8xl3B 

9x15 

cursor 

6x13 

6x10 

6x12 

8x13 

8xl3bold 

9x15 

cursor 

fixed 
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Filename 

Font  name 

courBOlO 

courB012 

courB014 

courB018 

courB024 

courBOOS 

courBlO 

courB12 

courB14 

courB18 

courB24 

courB08 

courOlO 

cour012 

cour014 

cour018 

cour024 

courO08 

courRIO 

courR12 

courR14 

courR18 

courR24 

courR08 

helvBOlO 

helvB012 

helvB014 

helvB018 
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-adobe-courier-bold-o-normal-  -10-1 00-7 5-75-m-60-iso8859- 1 
-adobe-courier-bold-o-normal-  -12-1 20-75-75-m-70-iso8859- 1 
-adobe-courier-bold-o-normal-  -14-140-75-75-m-90-iso8859-l 
-adobe-courier-bold-o-normal-  -18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-bold-o-normal-  -24-240-75-75-m-150-iso8859-l 
-adobe-courier-bold-o-normal-  -8-80-75-75-m-50-iso8859- 1 
-adobe-courier-bold-r-normal-  -10-100-75-75-m-60-iso8859-l 
-adobe-courier-bold-r-normal-  -12-120-75-75-m-70-iso8859-l 
-adobe-courier-bold-r-nc»mal-  -14-140-75-75-m-90-iso8859-l 
-adobe-courier-bold-r-normal-  - 1 8-1 80-75-75-m- 1 10-iso8859- 1 
-adobe-courier-bold-r-normal-  -24-240-75-75-m-150-iso8859-l 
-adobe-courier-bold-r-normal-  -8-80-75-75-m-50-iso8859-l 
-adobe-courier-medium-o-normal-  -10-100-75-75-m-60-iso8859-l 
-adobe-courier-medium -o-normal-  -12-120-75-75-m-70-iso8859-l 
-adobe-courier-medium-o-normal-  -14-140-75-75-m-90-iso8859-l 
-adobe-courier-medium-o-normal-  -18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-medium-o-normal-  -24-240-75-75-m-150-iso8859-l 
-adobe-courier-medium-o-normal-  -8-80-75-75-m-50-iso8859-l 
-adobe-courier-medium -r-normal-  -10-100-75-75-m-60-iso8859-l 
-adobe-courier-medium-r-normal-  -12-120-75-75-m-70-iso8859-l 
-adobe-courier-medium-r-normal-  -14-140-75-75-m-90-iso8859-l 
-adobe-courier-medium-r-normal-  -18-180-75-75-m-l  10-iso8859-l 
-adobe-courier-medium-r-normal-  -24-240-75-75-m- 1 50-iso8859- 1 
-adobe-courier-medium-r-normal-  -8-80-75-75-m-50-iso8859-l 
-adobe-helvetica-bold-o-normal-  -10-100-75-75-p-60-iso8859-l 
-adobe-helvetica-bold-o-normal-  -12-1 20-75-75 -p-69-iso8859- 1 
-adobe-helvetica-bold-o-normal-  -14-140-75-75-p-82-iso8859-l 
-adobe-helvetica-bold-o-normal-  -18-180-75-75-p-104-iso8859-l 
-adobe-helvetica-bold-o-normal-  -24-240-75-75-p-138-iso8859-l 
-adobe-helvetica-bold-o-normal-  -8-80-75-75-p-50-iso8859-l 
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ncenBI12 
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Font  name 

-adobe-helvetica-bold-r-normal-  -10-100-75-75-p-60-iso8859-l 
-adobe-helvetica-bold-r-normal-  -12-1 20-7 5-75 -p-70-iso8859- 1 
-adobe-helvetica-bold-r-normal-  - 14-140-7 5-7 5-p-82-iso8859- 1 
-adobe-helvetica-bold-r-normal-  -18-1 80-7 5-75-p-  103-iso8859- 1 
-adobe-helvetica-bold-r-normal-  -24-240-75-75-p-138-iso8859-l 
-adobe-helvetica-bold-r-normal-  -8-80-75-75-p-50-iso8859-l 
-adobe-helvetica-medium-o-normal-  -10-100-75-75-p-57-iso8859-l 
-adobe-helvetica-medium-o-normal-  -12-120-75-75-p-67-iso8859-l 
-adobe-helvetica-medium-o-normal-  -14-140-75-75-p-78-iso8859-l 
-adobe-helvetica-medium-o-normal-  -18-180-75-75-p-98-iso8859-l 
-adobe-helvetica-medium-o-normal-  -24-240-75-75-p-130-iso8859-l 
-adobe-helvetica-medium-o-normal-  -8-80-75-75-p-47-iso8859-l 
-adobe-helvetica-medium-r-normal-  -10-1 00-75-75-p-56-iso8859- 1 
-adobe-helvetica-medium-r-normal-  -12-120-75-75-p-67-iso8859-l 
-adobe-helvetica-medium-r-normal-  -14-140-75-75-p-77-iso8859-l 
-adobe-helvetica-medium-r-normal-  -18-180-75-75-p-98-iso8859-l 
-adobe-helvetica-medium-r-normal-  -24-240-75-75-p-130-iso8859-l 
-adobe-helvetica-medium-r-normal-  -8-80-75-75-p-46-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal- -10-100-75-75-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal--12-120-75-75-p-76-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal- -14-140-75-75-p-88-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal-  -18-180-75-75-p-lll-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal-  -24-240-75-75-p-148-iso8859-l 
-adobe-new  century  schoolbook-bold-i-normal-  -8-80-75-75-p-56-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal- -10-100-75-75-p-66-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal- -12-120-75-75-p-77-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal- -14-140-75-75-p-87-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal- -18-180-75-75-p-113-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal- -24-240-75-75-p-149-iso8859-l 
-adobe-new  century  schoolbook-bold-r-normal-  -8-80-75-75-p-56-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal--10-100-75-75-p-60-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal--12-120-75-75-p-70-iso8859-l 
-adobe-new  century  schoolbook-medium -i-normal-  -14-140-75-75-p-81-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal--18-180-75-75-p-104-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal-  -24-240-75-75-p-136-iso8859-l 
-adobe-new  century  schoolbook-medium-i-normal-  -8-80-75-75-p-50-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal--10-100-75-75-p-60-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal--12-120-75-75-p-70-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal-  -14-140-75-75-p-82-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal-  -18-180-75-75-p-103-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal-  -24-240-75-75-p-137-iso8859-l 
-adobe-new  century  schoolbook-medium-r-normal-  -8-80-75-75-p-50-iso8859-l 
-adobe-times-bold-i-normal-  -10-1 00-75-75-p-57-iso8859- 1 
-adobe-times-bold-i-normal--12-120-75-75-p-68-iso8859-l 
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-adobe-times-bold-i-normal-  -14-140-75-75-p-77-iso8859-l 
-adobe-times-bold-i-normal-  - 1 8-1 80-75-75-p-98-iso8859- 1 
-adobe-times-bold-i-normal-  -24-240-75-75-p-  128-iso8859- 1 
-adobe-times-bold-i-normal-  -8-80-75-75-p-47-iso8859-l 
-adobe-times-bold-r-normal--10-100-75-75-p-57-iso8859-l 
-adobe-times-bold-r-normal-  -12-120-75-75-p-67-iso8859-l 
-adobe-times-bold-r-normal-  -14-140-75-75-p-77-iso8859-l 
-adobe-times-bold-r-normal-  -18-180-75-75-p-99-iso8859-l 
-adobe-times-bold-r-normal-  -24-240-75-75-p- 132-iso8859-l 
-adobe-times-bold-r-normal-  -8-80-75-75-p-47-iso8859-l 
-adobe-times-medium-i-normal-  -10-100-75-75-p-52-iso8859-l 
-adobe-times-medium-i-normal-  -12-120-75-75-p-63-iso8859-l 
-adobe-times-medium-i-normal-  -14-140-75-75-p-73-iso8859-l 
-adobe-times-medium-i-normal-  -18-180-75-75-p-94-iso8859-l 
-adobe-times-medium-i-normal-  -24-240-75-75-p- 125-iso8859-l 
-adobe-times-medium-i-normal-  -8-80-75-75-p-42-iso8859- 1 
-adobe- times-medium-r-normal-  -10-100-75-75-p-54-iso8859-l 
-adobe-times-medium-r-normal-  -12-120-75-75-p-64-iso8859-l 
-adobe-times-medium-r-normal--14-140-75-75-p-74-iso8859-l 
-adobe-times-medium-r-normal-  -18-180-75-75-p-94-iso8859-l 
-adobe-times-medium-r-normal-  -24-240-75-75-p-124-iso8859-l 
-adobe-times-medium-r-normal-  -8-80-75-75-p-44-iso8859-l 
-bitstream-charter-bold-i-normal-  -10-100-75-75-p-62-iso8859-l 
-bitstream-charter-bold-i-normal-  -12-120-75-75-p-74-iso8859-l 
-bitstream-charter-bold-i-normal-  - 1 5-140-75-75-p-93-iso8859- 1 
-bitstream-charter-bold-i-normal-  -19-1 80-75-75-p- 1 1 7-iso8859- 1 
-bitstream-charter-bold-i-normal-  -25-240-75-75-p-154-iso8859-l 
-bitstream-charter-bold-i-normal-  -8-80-75-75-p-50-iso8859- 1 
-bitstream-charter-bold-r-normal-  -10-100-75-75-p-63-iso8859-l 
-bitstream-charter-bold-r-normal-  -12-120-75-75-p-75-iso8859-l 
-bitstream-charter-bold-r-normal-  -15-140-75-75-p-94-iso8859-l 
-bitstream-charter-bold-r-normal-  -19-180-75-75-p-119-iso8859-l 
-bitstream-charter-bold-r-normal-  -25-240-75-75-p-157-iso8859-l 
-bitstream-charter-bold-r-normal-  -8-80-75-75-p-50-iso8859- 1 
-bitstream-charter-medium-i-normal-  -10-100-75-75-p-55-iso8859-l 
-bitstream-charter-medium-i-normal-  -12-120-75-75-p-65-iso8859-l 
-bitstream-charter-medium-i-normal-  -15-140-75-75-p-82-iso8859-l 
-bitstream-charter-medium-i-normal-  - 19-1 80-75-75-p-  103-iso8859- 1 
-bitstream-charter-medium-i-normal-  -25-240-75-75-p-136-iso8859-l 
-bitstream-charter-medium-i-normal-  -8-80-75-75-p-44-iso8859- 1 
-bitstream-charter-medium-r-normal-  -10-100-75-75-p-56-iso8859- 1 
-bitstream-charter-medium-r-normal-  -12-120-75-75-p-67-iso8859-l 
-bitstream-charter-medium-r-normal-  -15-140-75-75-p-84-iso8859-l 
-bitstream-charter-medium-r-normal-  -19-1 80-75-75-p-  106-iso8859- 1 
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-bitstream-charter-medium-r-normal-  -8-80-75-75-p-45-iso8859- 1 
dec-adobe-symbol-medium-r-normal-  -10-100-75-75-p-61-adobe-fontspecific 
dec-adobe-symbol-medium-r-normal-  -12-1 20-7 5-75-p-74-adobe-fontspecific 
dec-adobe-symbol-medium-r-normal-  -14-140-75-75-p-85-adobe-fontspecific 
dec-adobe-symbol-medium-r-normal-  -18-180-75-75-p-107-adobe-fontspecific 
dec-adobe-symbol-medium-r-normal-  -24-240-75-75-p-142-adobe-fontspecific 
dec-adobe-symbol-medium-r-normal-  -8-80-75-75-p-51-adobe-fontspecific 
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-bitstream-charter-bold-i-normal-  -1 1-80- 100- 100-p-68-iso8859-l 
-bitstream-charter-bold-i-normal-  -14-100-100-1 00-p-86-iso8859- 1 
-bitstream-charter-bold-i-normal-  -17-1 20- 100-1 00-p- 1 05-iso8859- 1 
-bitstream-charter-bold-i-normal-  -19-140-100-100-p-l  17-iso8859-l 
-bitstream-charter-bold-i-normal-  -25-1 80- 100-1 00-p- 1 54-iso8859- 1 
-bitstream-charter-bold-i-normal-  -33-240-100-100-p-203-iso8859-l 
-bitstream-charter-bold-r-normal-  -1 1-80- 100-1 00-p-69-iso8859-l 
-bitstream-charter-bold-r-normal-  -14-100-100-1 00-p-88-iso8859- 1 
-bitstream-charter-bold-r-normal-  -17-120-100-1 00-p- 1 07-iso8859- 1 
-bitstream-charter-bold-r-normal-  -19-140-100-100-p-l  19-iso8859-l 
-bitstream-charter-bold-r-normal-  -25-1 80- 1 00- 1 00-p- 1 57-iso8859- 1 
-bitstream-charter-bold-r-normal-  -33-240-100-100-p-206-iso8859-l 
-bitstream-charter-medium-i-normal-  -1 1-80-1 00-1 00-p-60-iso8859-l 
-bitstream-charter-medium-i-normal-  -14-100-100-1 00-p-76-iso8859- 1 
-bitstream-charter-medium-i-normal-  -17-120-100-1 00-p-92-iso8859- 1 
-bitstream-charter-medium-i-normal-  - 19- 140- 100-  100-p-  103-iso8859-l 
-bitstream-charter-medium-i-normal-  -25-180-100-100-p-136-iso8859-l 
-bitstream-charter-medium-i-normal-  -33-240-100-100-p-179-iso8859-l 
-bitstream-charter-medium-r-normal-  - 1 1 -80- 100-  100-p-61  -iso8859- 1 
-bitstream-charter-medium-r-normal- - 14- 1 00- 1 00- 1 00-p-78-iso8859- 1 
-bitstream-charter-medium-r-normal- - 1 7- 1 20- 1 00- 1 00-p-95-iso8859- 1 
-bitstream-charter-medium-r-normal-  -19-140-100-1 00-p- 1 06-iso8859- 1 
-bitstream-charter-medium-r-normal-  -25- 1 80-100- 1 00-p- 1 39-iso8859- 1 
-bitstream-charter-medium-r-normal-  -33-240-100-100-p-183-iso8859-l 
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Example  E-l  is  the  source  code  for  the  xshowfonts  program,  which  we  used  to  create  most  of 
the  illustrations  in  this  appendix.  If  you  don’t  want  to  type  it  in,  you  can  find  instructions  for 
getting  it  online  in  the  Preface. 

Example  E-1.  xshowfont  source  listing 

/*  Dan  Heller  <argv@sun . com>,  based  on  a design  by  Tim  O'Reilly 
★ 

* xshowfonts.c  - 

* Displays  a set  of  fonts  specified  on  the  command  line,  from 

* a pipe,  or  typed  into  stdin.  Fonts  can  be  specified  as  specific 

* fonts  or  as  wildcard  character  strings.  A pixmap  is  created  to 

* display  all  the  fonts.  This  is  done  by  using  the  pixmap  as  the 

* pixmap  image  for  a label  widget.  Each  font  prints  its  own  name 

* in  its  own  font  style  — the  -phrase  option  prints  the  phrase 

* instead. 

* 

* All  fonts  are  loaded  first  and  scanned  to  determine  the  total 

* width  and  height  of  the  pixmap  first.  Then  the  fonts  are 

* reopened  again  to  actually  render  the  fonts  into  the  pixmap. 

* All  this  could  be  avoided  by  using  XListFontsWithlnf o ( ) 

* rather  than  XListFonts ( ) , but  since  the  list  is  potentially 

* very  large,  I didn't  want  to  overload  the  server  and  client 

* with  all  those  fonts  + a very  large  pixmap. 

* 

* Usage:  xshowfonts 

* -s  sorts  the  fonts  in  alphabetical  order  before  displaying 

them . 

* -v  verbose  mode  for  when  input  is  redirected  to  stdin. 

* -w  width  of  viewport  window 

* -h  height  of  viewport  window 

* -fg  foreground_color 

* -bg  background_color 

* -phrase  "text  string"  (otherwise,  name  of  font  is  used) 

* —indicates  to  read  from  stdin.  Piping  doesn't  require 

the  '-'  argument.  With  no  arguments,  xshowfonts  reads 

* from  stdin  anyway. 

* 

* Neat  ways  to  use  the  program: 

* xshowfonts  -fg  green  -bg  black  "*adobe*" 

* xshowfonts  -sort 

* xshowfonts  -phrase  "The  quick  brown  fox  jumps  over  the  lazy 

* dog"  "*times*" 

* xlsfonts  | xshowfonts  -sort 

* xshowfonts  "*helvetica* " 

* 

* compile:  (triple  click  and  paste  next  line) 

cc  -0  -s  xshowfonts.c  -lXaw  -lXt  -lXmu  -1X11  -o  xshowfonts 

*/ 

tinclude  <stdio.h> 
tinclude  <X1 1/Intrinsic . h> 
tinclude  <Xll/StringDefs . h> 
tinclude  <X11/Xaw/Label .h> 
tinclude  <Xll/Xaw/Viewport .h> 

struct  _resrcs  { 
int  sort; 
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Example  E-1.  xshowfont  source  listing  (continued) 


int  verbose; 

Pixel  fg,  bg; 
char  *phrase; 

int  viewwidth,  viewheight; 
} Resrcs; 


static  XtResource  resources []  = { 

{ "sort",  "Sort",  XtRBoolean,  sizeof  (int), 

XtOffsetOf (struct  _resrcs, sort ) , XtRImmediate, 

False  } , 

{ "verbose",  "Verbose",  XtRBoolean,  sizeof  (int), 
XtOffsetOf (struct  _resrcs, verbose) , XtRImmediate, 

False  }, 

{ "foreground",  "Foreground",  XtRPixel,  sizeof  (Pixel), 
XtOffsetOf (struct  resrcs, fg),  XtRString, 
XtDefaultForeground  }, 

{ "background",  "Background",  XtRPixel,  sizeof  (Pixel), 
XtOff setOf ( struct  resrcs, bg),  XtRString, 
XtDefaultBackground  }, 

{ "phrase",  "Phrase",  XtRString,  sizeof  (String), 
XtOffsetOf (struct  _resrcs, phrase) , XtRImmediate,  NULL  }, 
{ "view-width",  "View-width",  XtRInt,  sizeof  (int), 

XtOff setOf (struct  resrcs, viewwidth) , XtRImmediate, 
(char  *)500  ), 

{ "view-height",  "View-height",  XtRInt,  sizeof  (int), 
XtOffsetOf (struct  resrcs , viewheight ) , XtRImmediate, 
(char  *)300  }, 

} ; 

static  XrmOptionDescRec  options []  = { 

{ "-sort",  "sort",  XrmoptionNoArg,  "True"  }, 

{ "-v",  "verbose",  XrmoptionNoArg,  "True"  }, 

{ "-fg",  "foreground",  XrmoptionSepArg,  NULL  }, 

{ "-bg",  "background",  XrmoptionSepArg,  NULL  }, 

{ "-phrase",  "phrase",  XrmoptionSepArg,  NULL  }, 

{ "-w",  "view-width",  XrmoptionSepArg,  NULL  }, 

{ "-h",  "view-height",  XrmoptionSepArg,  NULL  }, 

} ; 


/*  sort  font  according  to  the  following  parameters. 

* font  specs  we're  interested  in: 

* -f ndry-fmly-wght-slant-*swdth-*adstyl-*pxlsz-ptsz-  . . . . 

* foundry  — sort  by  foundry  first;  similar  ones  are  always 

* grouped  together 

* weight  — medium,  demi-bold,  bold 

* slant  — roman,  italic/oblique,  reverse  italic/obligue 

* (i  or  o,  r,  ri,  ro) 

* ptsize  — increase  numerical  order 
*/ 


font_cmp(fl,  f2) 
char  **fl,  * *f2 ; 

{ 

char  fndryl[16],  fmlyl[64],  wghtl[32],  slantl[3]; 
char  fndry2[16],  fmly2[64],  wght2[32],  slant2[3]; 
int  n,  m,  ptsizel,  ptsize2; 

char  * f ont  fmt  str  = “0-9] % 

*d-%d-" ; 
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Example  E-1.  xshowfont  source  listing  (continued) 

n = sscanf (*fl,  font_fmt_str,  fndryl,  fmlyl,  wghtl,  slantl, 
&ptsizel ) ; 

m = sscanf (*f2,  font_fmt_str,  fndry2,  fmly2,  wght2,  slant2, 
&ptsize2) ; 
if  (m  < 5 ||  n < 5) 

/*  font  not  in  correct  format  — just  return  font  names 
* in  order  */ 
return  strcmp (*fl,  *f2) ; 

if  (n  = strcmp (fndryl,  fndry2) ) 

return  n;  /*  different  foundries  — return  alphabetical 

* order  */ 

if  (n  = strcmp (fmlyl , fmly2) ) 

return  n;  /*  different  families  — return  alphabetical 

* order  */ 

if  (n  = strcmp (wghtl , wght2) ) 

return  -n;  /*  weight  happens  to  be  correct  in  reverse 
* alpha  order  */ 
if  (n  = strcmp (slantl,  slant2)) 

return  n;  /*  slants  happen  to  be  correct  in  alphabetical 

* order  */ 

/*  sort  according  to  point  size  */ 
return  ptsizel  - ptsize2; 

} 

main (argc,  argv) 
int  argc; 
char  *argv [ ] ; 

{ 

Widget  topLevel,  vp; 

char  **list  = (char  **)NULL,  **tmp; 

char  buf [ 128 ] ; 

extern  char  * *XListFonts ( ) ; 

extern  int  strcmp (); 

XFontStruct  *font; 

Pixmap  pixmap; 

GC  gc  ; 

Display  *dpy; 

int  istty  = isatty(O),  redirect  = listty,  i,  j,  total  = 0; 
unsigned  int  w,  width  = 0,  height  = 0; 

topLevel  = Xt Initialize (argv [ 0 ] , argv[0],  options, 

XtNumber (options) , Sargc,  argv) ; 
dpy  = XtDisplay (topLevel) ; 

XtGetApplicationResources (topLevel,  SResrcs, 
resources,  XtNumber (resources) , NULL,  0); 

if  { ! argv [ 1 ] ||  ! strcmp (argv [ 1 ] , "-"))  { 

printf ( "Loading  fonts  from  input.  ") ; 
if  (istty)  { 

puts ("End  with  EOF  or  ."); 
redirect++; 

} else 

puts ("Use  —v  to  view  font  names  being  loaded."); 

} else  if  (listty  &&  strcmp (argv [ 1 ] , "-")) 
printf ("%s:  either  use  pipes  or  specify  font  names  — 
not  both.\n". 
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Example  E-1.  xshowfont  source  listing  (continued) 

argv [0] ) , exit (1) ; 
while  (*++argv  I I redirect)  { 
if  (Iredirect) 

if  ( ! strcmp ( *argv, 
redirect!!; 
else 

strcpy(buf,  *argv) ; 
if  (redirect)  { 
if  (istty) 

printf ( "Fontname : "),  f flush (stdout) ; 
if  (!fgets(buf,  sizeof  buf,  stdin)  I I 
!strcmp(buf,  ".\n")) 

break; 

buf [ strlen (buf ) -1 ] = 0; 

} 

if  ( ! buf [ 0 ] ) 
continue; 

if  (istty  ||  Resrcs . verbose) 
printf ("Loading 

tmp  - XListFonts (dpy,  buf,  32767,  &i) ; 
if  (i  ==  0)  { 

print f ( "couldn' t load  font  "); 
if  (listty  &&  ! Resrcs . verbose) 
printf ( " 
putchar ( ' \n'  ) ; 
continue; 

} 

if  (istty  ||  Resrcs . verbose) 

printf ("%d  font%s\n",  i,  i ==  1?  ""  : "s"); 
if  (Hist)  { 

list  = tmp; 
total  = i; 

} else  { 

i +=  total; 

if  (!(list  = (char  * * ) XtRealloc ( list , i * 
sizeof  (char  * ) ) ) ) 

XtError("Not  enough  memory  for  font  names"); 
for  (j  = 0;  total  < i;  j++,  total++) 
list [total]  = tmp[j]; 

} 

) 

if  (total  ==  0) 
puts ("No  fonts?!"),  exit(l); 
print f ( "Total  fonts  loaded:  %d\n",  total); 
if  (Resrcs . sort ) { 

print f ( "Sort ing  fonts..."),  f flush (stdout ) ; 
qsort(list,  total,  sizeof  (char  *),  font_cmp) ; 
putchar ( ' \n' ) ; 

} 

/*  calculate  size  for  pixmap  by  getting  the  dimensions 
* of  each  font  */ 

puts ( "Calculating  sizes  for  pixmap."); 
for  (i  =0;  i < total;  i++)  { 

if  (!(font  = XLoadQueryFont (dpy , list[i])))  { 
printf ( "Can' t load  font:  %s\n",  list[i]); 
continue; 
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Example  E-1.  xshowfont  source  listing  (continued) 

) 

if  ( (w  = XTextWidth (font,  list[i], 
strlen  (list [i] ) ) ) > width) 
width  = w; 

height  +=  font->ascent  + font->descent ; 

XFreeFont (dpy,  font) ; 

} 

width  +=  6; 
height  +=  6; 

/*  Create  pixmap  + GC  */ 

printf ( "Creating  pixmap  of  size  %dx%d\n",  width,  height); 
if  (! (pixmap  = XCreatePixmap (dpy,  Def aultRootWindow (dpy ) , 
width,  height,  Def aultDepth (dpy , Def aultScreen (dpy) ) ) ) ) 
XtError ( "Can' t Create  pixmap"); 
if  (!(gc  = XCreateGC (dpy,  pixmap,  NULL,  0))) 

XtError ("Can' t create  gc"); 

XSetForeground (dpy,  gc,  Resrcs.bg); 

XFillRectangle (dpy,  pixmap,  gc,  0,  0,  width,  height); 
XSetForeground (dpy,  gc,  Resrcs.fg); 

XSetBackground (dpy , gc,  Resrcs.bg); 
height  = 0; 

for  (i  = 0;  i < total;  i++)  { 

if  (!(font  = XLoadQueryFont (dpy,  list[i]))) 

continue;  /*  it's  already  been  reported  */ 

XSetFont (dpy,  gc,  font->fid) ; 
height  +=  font->ascent ; 
if  (Resrcs .phrase) 

XDrawString (dpy , pixmap,  gc,  0,  height, 

Resrcs .phrase,  strlen  (Resrcs .phrase) ) ; 

else 

XDrawString (dpy,  pixmap,  gc,  5,  height,  list[i], 
strlen (list [ i] ) ) ; 
height  +=  f ont->descent ; 

XFreeFont (dpy,  font); 

} 

vp  = XtVaCreateManagedWidget ( "viewport " , viewportWidgetClass, 
topLevel , 

XtNallowHoriz , True, 

XtNallowVert , True, 

XtNwidth,  Resrcs . view_width, 

XtNheight,  Resrcs . viewheight , 

NULL) ; 

XtVaCreateManagedWidget ("foo",  labelWidgetClass,  vp, 
XtNbitmap,  pixmap, 

NULL) ; 

if  (Iredirect) 

XFreeFontNames (list) ; 

XtRealizeWidget (topLevel) ; 

XtMainLoop ( ) ; 
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xterm  Control  Sequences 


This  appendix  list  the  escape  sequences  that  can  be  used  to  control  features 
of  an  xterm  window  or  its  terminal  emulation. 


In  This  Chapter: 


xterm  Control  Sequences  681 

Definitions 681 

VT102  Mode 681 

Tektronix  4014  Mode  688 
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xterm  Control  Sequences 


A standard  terminal  performs  many  operations  in  response  to  escape  sequences  sent  out  by  a 
program.  In  emulating  a terminal,  xterm  responds  to  those  same  terminal  escape  sequences. 
Under  UNIX,  programs  use  the  termcap  or  terminfo  database  to  determine  which  escape 
sequences  to  send  out.  For  more  information,  see  the  standard  UNIX  man  pages  termcap( 5) 
or  terminfo( 5),  or  the  Nutshell  Handbook  Termcap  and  Terminfo , available  from  O’Reilly  & 
Associates,  Inc. 


xterm  Control  Sequences 

This  appendix  is  based  on  two  sources:  the  “Xterm  Control  Sequences”  document,  written 
by  Edward  Moy,  University  of  California,  Berkeley,  for  the  X10  xterm ; and  XI 1 updates  pro- 
vided to  the  X Consortium  by  Skip  Montanaro,  GE  Corporate  Research  & Development. 


Definitions 

C A single  (required)  character. 

Ps  A single  (usually  optional)  numeric  parameter,  composed  of  one  of  more  digits. 

Pm  A multiple  numeric  parameter  composed  of  any  number  of  single  numeric  parameters, 
separated  by  0 character(s). 

Pt  A text  parameter  composed  of  printable  characters. 

VT102  Mode 

Most  of  these  control  sequences  are  standard  VT102  control  sequences.  There  are,  however, 
additional  ones  to  provide  control  of  xterm -dependent  functions,  like  the  scrollbar  or  window 
size. 
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|bel| 

Bell  (Ctrl-G) 

Backspace  (Ctrl-H) 

|tab| 

Horizontal  Tab  (Ctrl-I) 

0 

Line  Feed  or  New  Line  (Ctrl-J) 

0 

Vertical  Tab  (Ctrl-K) 

0 

Form  Feed  or  New  Page  (Ctrl-L) 

@ 

Carriage  Return  (Ctrl-M) 

Shift  Out  (Ctrl-N)  — > Switch  to  Alternate  Character  Set 

0 

Shift  In  (Ctrl-O)  — » Switch  to  Standard  Character  Set 

| ESC  ||  BEL  | 

Same  as  non-escaped  BEL 

|esc||bs| 

Same  as  non-escaped  BS 

|esc||ht| 

Same  as  non-escaped  HT 

|esc||nl| 

Same  as  non-escaped  NL 

|esc||vt| 

Same  as  non-escaped  VT 

|esc||np| 

Same  as  non-escaped  NP 

|esc||cr| 

Same  as  non-escaped  CR 

[escJ^oJ 

Same  as  non-escaped  SO 

| ESC  ||  SI  | 

Same  as  non-escaped  SI 

|esc||#||bel| 

Same  as  non-escaped  BEL 

[esc  |#|[bs] 

Same  as  non-escaped  BS 

|esc||#|[~ht1 

Same  as  non-escaped  HT 

[esc1[#1[nl1 

Same  as  non-escaped  NL 

|esc||#1[vt| 

Same  as  non-escaped  VT 

Same  as  non-escaped  NP 

[esc1[#1[cr] 

Same  as  non-escaped  CR 

|esc||#|[so| 

Same  as  non-escaped  SO 

[escJI#J[sF| 

Same  as  non-escaped  SI 

sss 

DEC  Screen  Alignment  Test  (DECALN) 

|esc||(||bel| 

Same  as  non-escaped  BEL 

[escJKJ[bs| 

Same  as  non-escaped  BS 

[escJI^J  [ht] 

Same  as  non-escaped  HT 

IescJKJInl] 

Same  as  non-escaped  NL 

[esc  ||(  II  vt] 

Same  as  non-escaped  VT 

|esc||(||np| 

Same  as  non-escaped  NP 

|esc||(||cr| 

Same  as  non-escaped  CR 

[escJKJ[so] 

Same  as  non-escaped  SO 
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|esc||(||si| 

Same  as  non-escaped  SI 

|eSc||(|c 

Select  GO  Character  Set  (SCS) 

C = ®->  Special  Character  and  Line  Drawing  Set 
C = [T]  — » Alternate  Character  ROM  Standard  Set 

C = \2\  — > Alternate  Character  ROM  Special  Set 

C = [a]  — > United  Kingdom  (UK) 

C = [b]  — > United  States  (US  ASCII) 

|esc||)|c 

Select  G1  Character  Set  (SCS) 

C = [0]->  Special  Character  and  Line  Drawing  Set 
C = [T]  — > Alternate  Character  ROM  Standard  Set 

C = [ 2]  ->  Alternate  Character  ROM  Special  Set 

C = H->  United  Kingdom  (UK) 

C = [b]  -»  United  States  (US ASCII) 

|esc||*|c 

Select  G2  Character  Set  (SCS) 

C = [0]  — > Special  Character  and  Line  Drawing  Set 
C = [fl^  Alternate  Character  ROM  Standard  Set 
C = [ 2]  — > Alternate  Character  ROM  Special  Set 

C = [a]  — > United  Kingdom  (UK) 

C = [b]  — > United  States  (US  ASCII) 

|esc||+|c 

Select  G3  Character  Set  (SCS) 

C = [0]  — > Special  Character  and  Line  Drawing  Set 
C = Q]  -»  Alternate  Character  ROM  Standard  Set 
C = [ 1]  — > Alternate  Character  ROM  Special  Set 

C = \a\  — > United  Kingdom  (UK) 

C = E ->  United  States  (US ASCII) 

|esc||7| 

Save  Cursor  (DECSC) 

|esc||  8 1 

Restore  Cursor  (DECRC) 

|esc|1=J 

Application  Keypad  (DECPAM) 

|esc||>  | 

Normal  Keypad  (DECPNM) 

|esc||dI 

Index  (IND) 

|esc||eI 

Next  Line  (NEL) 

|esc||hI 

Tab  Set  (HTS) 

IescIImI 

Reverse  Index  (RI) 

|esc||n| 

Single  Shift  Select  of  G2  Character  Set  (SS2) 

IescIIoI 

Single  Shift  Select  of  G3  Character  Set  (SS3) 

(esc | Return  Terminal  ID  (DECID) 
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|esc||[||bel| 

Same  as  non-escaped  BEL 

[Escimfisl 

Same  as  non-escaped  BS 

[esc1H1[ht1 

Same  as  non-escaped  HT 

[iscitnw 

Same  as  non-escaped  NL 

[escIHIFvtI 

Same  as  non-escaped  VT 

[eSc][H[np1 

Same  as  non-escaped  NP 

[iscirnicRi 

Same  as  non-escaped  CR 

[iscllTIfso] 

Same  as  non-escaped  SO 

ram 

Same  as  non-escaped  SI 

|esc||[]|?||bel| 

Same  as  non-escaped  BEL 

[esc1[H[?i[bs] 

Same  as  non-escaped  BS 

[esc1[H[?i[ht1 

Same  as  non-escaped  HT 

[ES^im[?1[NLl 

Same  as  non-escaped  NL 

[esc][T1[?][vt1 

Same  as  non-escaped  VT 

[esc1[H[?i[np1 

Same  as  non-escaped  NP 

Same  as  non-escaped  CR 

[isc1[TI[?][so1 

Same  as  non-escaped  SO 

wfiirn 

Same  as  non-escaped  SI 

1esc||  [\ps\@\ 

Insert  Ps  (Blank)  Character(s)  (default  =1)  (ICH) 

IescJLH/^LaJ 

Cursor  Up  Ps  Times  (default  = 1)  (CUU) 

IescJUJ/^IbJ 

Cursor  Down  Ps  Times  (default  =1)  (CUD) 

[escJ[U^[cJ 

Cursor  Forward  Ps  Times  (default  = 1)  (CUF) 

IescJ[U^[dJ 

Cursor  Backward  Ps  Times  (default  = 1)  (CUB) 

llscJiU^U^lHj 

Cursor  Position  [row;column]  (default  = [1,1])  (CUP) 

[esc1HI/^[j1 

Erase  in  Display  (ED) 

= [o]  — > Clear  Below  (default) 

Ps  = [T]  — » Clear  Above 
= [2]  — > Clear  All 

Erase  in  Line  (EL) 

Ps  = [0]  — > Clear  to  Right  (default) 

= [U  — > Clear  to  Left 

Ps  = \2\  — > Clear  All 

WH1/>[L] 

Insert  Ps  Line(s)  (default  = 1)  (IL) 

[escJUJ/^[M] 

Delete  Ps  Line(s)  (default  =1)  (DL) 

|esc|1[|/^|p1 

Delete  Ps  Character(s)  (default  = 1)  (DCH) 

iHscimpfi 

Track  mouse 
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[jscim^ici 

ram^iii 


ESC 


BkH 


[escIHIPjIH 


Escim^fml 


[escIEPjE 


[meEII^S^S 


Device  Attributes  (DAI) 

Cursor  Position  [row;column]  (default  = [1,1])  (HVP) 

Tab  Clear 

Ps  = [o]  — > Clear  Current  Column  (default) 

Ps  = \3\  ->  Clear  All 
Mode  Set  (SET) 

Ps  = 0 -» Insert  Mode  (IRM) 

Ps  = \M  — > Automatic  Linefeed  (LNM) 

Mode  Reset  (RST) 

Ps  = @ — > Insert  Mode  (IRM) 

Ps  = [JO  -»  Automatic  Linefeed  (LNM) 

Character  Attributes  (SGR) 

= E — > Normal  (default) 

= fl  — > Blink  (appears  as  Bold) 

Pm  - B -»  Underscore 
Pm  = 0->Bold 
Pm  = 0 —3 > Inverse 
Device  Status  Report  (DSR) 

Ps  = 5 — » Status  Report  [escJEEE  — > OK 
/^  = 6 — > Report  Cursor  Position  (CPR)  [row;column]  as 
[HsclErEclRl 

Set  Scrolling  Region  [top;bottom]  (default  = full  size  of  window) 


(DECSTBM) 

I esc  IE  ^[71  Request  Terminal  Parameters  (DECREQTPARM) 

[esc]  ps  ND  string  NP  OSC  Mode 

ND  can  be  any  non-digit  Character  (it’s  discarded) 

NP  can  be  any  non-printing  Character  (it’s  discarded) 
string  can  be  any  ASCII  printable  string  (max  511  characters) 
Ps  = \0\  — > use  string  as  a new  icon  name  and  title 
Ps  = E — > use  string  as  a new  icon  name  only 
Ps  = E — > use  string  as  a new  title  only 
Ps  = EE  — > use  string  as  a new  log  file  name 
IescIEE^E  DEC  Private  Mode  Set  (DECSET) 

Ps  = E — > Application  Cursor  Keys  (DECCKM) 

7*  =5|  ->SetVT52  Mode 

Ps  = E — > 132  Column  Mode  (DECCOLM) 
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Ps  = 0 -»  Smooth  (Slow)  Scroll  (DECSCLM) 

Ps  = E]  ->  Reverse  Video  (DECSCNM) 

Ps  = 0 ->  Origin  Mode  (DECOM) 

Ps  = 111  ->  Wraparound  Mode  (DECAWM) 

Ps  = 51  ->  Auto-repeat  Keys  (DECARM) 

Ps  = [9]  — > Send  MIT  Mouse  Row  & Column  on  Button  Press 
Ps  = 00  ->  Enter  TekTronix  Mode  (DECTEK) 

Ps  = 00  — > Allow  80  o 132  Mode 
Ps  = 00  ->  curses( 5)  fix 

P,  = 00  — > Turn  On  Margin  Bell 
Ps  = 00  ~ > Reverse- wraparound  Mode 
^ = 00  — » Start  Logging 
^ = 00  — > Use  Alternate  Screen  Buffer 
Ps  = 0000  -»  send  VT200  Mouse  Row  & Column  on  Button 
Press 

Ps  = 0000  — > send  VT200  Hilite  Mouse  Row  & Column  on 
Button  Press 

00B0^[[|  DEC  Private  Mode  Reset  (DECRST) 

Ps  = 0 ->  Normal  Cursor  Keys  (DECCKM) 

Ps  = 0 -»  80  Column  Mode  (DECCOLM) 

Ps  = 0 ->  Jump  (Fast)  Scroll  (DECSCLM) 

Ps  = 0 ->  Normal  Video  (DECSCNM) 

Ps  = 0 ->  Normal  Cursor  Mode  (DECOM) 
ps  = 0 No  Wraparound  Mode  (DECAWM) 
ps  = 0 -»  No  Auto-repeat  Keys  (DECARM) 

P*  = ® Don,t  Send  MIT  Mouse  Row  & Column  on  Button  Press 

PS  = 00  -»  Disallow  80  o 132  Mode 

Ps  = 00  ->  No  curses( 5)  fix 

Ps  = 00  — > Turn  Off  Margin  Bell 

Ps  = 00  — > No  Reverse-wraparound  Mode 

Ps  = 00  Stop  Logging 

Ps  = 00  —>  Use  Normal  Screen  Buffer 

ps  = 0000  ->  Don’t  send  Mouse  Row  & Column  on  Button  Press 
Ps  - 0000  — > Don  t send  Hilite  Mouse  Row  & Column  on  Button 
Press 
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1 esc  ||TI 0/^.lrl  Restore  DEC  Private  Mode 

Ps  = 0 — > Normal/ Application  Cursor  Keys  (DECCKM) 

Ps  = 0 -4  80/132  Column  Mode  (DECCOLM) 

Ps  - 0 Jump  (Fast)/Smooth  (Slow)  Scroll  (DECSCLM) 

= [5]  — > Normal/Reverse  Video  (DECSCNM) 

Ps  = [6]  — > Normal/Origin  Cursor  Mode  (DECOM) 

Ps  = 0 — > No  Wraparound/Wraparound  Mode  (DECAWM) 

= [8]  — > Auto-repeat/No  Auto-repeat  Keys  (DECARM) 

Ps  = [9]  — » Don’t  Send/Send  MIT  Mouse  Row  & Column  on  Button 
Press 

Ps  = @0  — » Disallow/ Allow  80  <->  132  Mode 
Ps  = @5]  —a > Off/On  curses( 5)  fix 
Ps  = @0  — > Turn  Off/On  Margin  Bell 
Ps  = 00  — » No  Reverse- wraparound/Reverse- wraparound  Mode 
Ps  = 00  — > Stop/S  tart  Logging 
Ps  = 00  — > Use  Normal/ Alternate  Screen  Buffer 
Ps  = 0000  — > Don’t  send/send  VT200  Mouse  Row  & Column  on 
Button  Press 

Ps  = 0000  ->  Don’t  send/send  VT200  Hilite  Mouse  Row  & 
Column  on  Button  Press 

lEsc|[[]f?1/^fs1  Save  DEC  Private  Mode 

Ps  = 0 — > Normal/ Application  Cursor  Keys  (DECCKM) 

Ps  = 0 ->  80/132  Column  Mode  (DECCOLM) 

Ps  ~ 0 Jump  (Fast)/Smooth  (Slow)  Scroll  (DECSCLM) 

Ps  = 0 Normal/Reverse  Video  (DECSCNM) 

Ps  = 0 -»  Normal/Origin  Cursor  Mode  (DECOM) 

Ps  = 0 ->  No  Wraparound/Wraparound  Mode  (DECAWM) 

Ps  = 0 — » Auto-repeat/No  Auto-repeat  Keys  (DECARM) 

Ps  = 0 — » Don’t  Send/Send  MIT  Mouse  Row  & Column  on  Button 
Press 

Ps  = 00  — » Disallow/Allow  80  o 132  Mode 

Ps  = 00  —>  Off/On  curses( 5)  fix 

Ps  = 00  ->  Turn  Off/On  Margin  Bell 

Ps  = 00  -»  No  Reverse- wraparound/Reverse- wraparound  Mode 

Ps  = 00  — > Stop/Start  Logging 

Ps  = 00  ->  Use  Normal/Altemate  Screen  Buffer 
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Ps  = [TI[oI00  — > Don’t  send/send  VT200  Mouse  Row  & Column  on 
Button  Press 

Ps  = [T][o][o][3]  ->  Don’t  send/send  VT200  Hilite  Mouse  Row  & 
Column  on  Button  Press 

lEScim^m Pt I bel | Set  Text  Parameters 

= [o]  — > Change  Window  Name  and  Title  to  Pt 
Ps  = [I]  -»  Change  Window  Name  to  Pt 
Ps  = 51  ->  Change  Window  Title  to  Pt 
Ps  = SJB  — > Change  Log  File  to  Pt 
Ps  = SB  -»  Change  Font  to  Pt 
Full  Reset  (RIS) 

Locking  Shift  Select  of  G2  Character  Set  (LS2) 

Locking  Shift  Select  of  G3  Character  Set  (LS3) 

Tektronix  4014  Mode 

Most  of  these  sequences  are  standard  Tektronix  4014  control  sequences.  The  major  features 
missing  are  the  alternate  (APL)  character  set  and  the  write-thru  and  defocused  modes. 


S0 

I ESC  I 


[bel| 

Bell  (Ctrl-G) 

@ 

Backspace  (Ctrl-H) 

[tab] 

Horizontal  Tab  (Ctrl-I) 

0 

Line  Feed  or  New  Line  (Ctrl-J) 

[0 

Vertical  Tab  (Ctrl-K) 

0 

Form  Feed  or  New  Page  (Ctrl-L) 

0] 

Carriage  Return  (Ctrl-M) 

|esc||etx| 

Switch  to  VT102  Mode 

|esc||enq| 

Return  Terminal  Status 

[escIIlf! 

PAGE  (Clear  Screen) 

|esc||etb| 

COPY  (Save  Tektronix  Codes  to  File) 

|esc||can| 

Bypass  Condition 

| ESC  II  SUB  1 

GIN  mode 

|esc||fs| 

Special  Point  Plot  Mode 

|esc||gs| 

Graph  Mode  (same  as  0) 

|esc||rs| 

Incremental  Plot  Mode  (same  as  0) 

| ESC  II  US  | 

Alpha  Mode  (same  as  [us]) 

[escJ18| 

Select  Large  Character  Set 
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ESC 


[esc 


SE 

S0 

[isclfbl 

fisclfcl 

[escIE 

[isc][h 


fisclfpl 

lEsc|[q] 

SB 

[isc]  [si 

[esciiti 

@ 

@ 

[rs] 


Select  #2  Character  Set 
Select  #3  Character  Set 
Select  Small  Character  Set 
Set  Text  Parameters 

Ps  = E — > Change  Window  Name  and  Title  to  Pt 

Ps  = [l]  — > Change  Icon  Name  to  Pt 

Ps  = \2\  ->  Change  Window  Title  to  Pt 

Ps  = 00  — > Change  Log  File  to  P, 

Normal  Z Axis  and  Normal  (solid)  Vectors 
Normal  Z Axis  and  Dotted  Line  Vectors 
Normal  Z Axis  and  Dot-Dashed  Vectors 
Normal  Z Axis  and  Short-Dashed  Vectors 
Normal  Z Axis  and  Long-Dashed  Vectors 
Defocused  Z Axis  and  Normal  (solid)  Vectors 
Defocused  Z Axis  and  Dotted  Line  Vectors 
Defocused  Z Axis  and  Dot-Dashed  Vectors 
Defocused  Z Axis  and  Short-Dashed  Vectors 
Defocused  Z Axis  and  Long-Dashed  Vectors 
Write-Thru  Mode  and  Normal  (solid)  Vectors 
Write-Thru  Mode  and  Dotted  Line  Vectors 
Write-Thru  Mode  and  Dot-Dashed  Vectors 
Write-Thru  Mode  and  Short-Dashed  Vectors 
Write-Thru  Mode  and  Long-Dashed  Vectors 
Point  Plot  Mode 
Graph  Mode 
Incremental  Plot  Mode 
Alpha  Mode 
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Standard  Bitmaps 


This  appendix  shows  the  bitmaps  included  with  the  standard  distribution  of 
the  X Window  System.  These  can  be  used  for  setting  window  background, 
cursor  symbols,  pixmaps,  and  possibly  for  application  icon  pixmaps. 


G 

Standard  Bitmaps 


A number  of  bitmaps  are  included  with  the  standard  distribution  of  the  X Window  System. 
These  bitmaps  can  be  used  for  setting  window  background  pixmaps  and  possibly  for  applica- 
tion icon  pixmaps. 

By  default,  the  standard  bitmaps  are  located  in  the  directory  I usr I include  1X1 1 /bitmaps . Each 
bitmap  is  in  standard  XI 1 bitmap  format  in  its  own  file.  The  bitmap  application  can  be  used 
to  view  these  bitmaps  in  larger  scale  and  to  edit  them  (though  their  permissions  normally  do 
not  allow  overwriting). 

You  can  use  these  bitmaps  to  set  the  background  pattern  of  a window  in  any  application  that 
allows  it.  For  example,  if  you  wanted  to  change  the  root  window  background  pixmap,  you 
could  do  so  using  xsetroot  as  follows: 

xsetroot  -bitmap  /usr/include/Xl l/bitmaps/wide_weave 

Note  that  the  bitmaps  that  come  in  pairs,  such  as  cntr_ptr  and  cntr_ptrmsk,  are 
intended  for  creating  pointer  shapes.  See  Chapter  11,  Setup  Clients , for  information  on  spec- 
ifying a bitmap  as  the  root  window  pointer. 

The  63  bitmaps  pictured  on  the  following  pages  are  included  in  the  Release  4 standard  distri- 
bution of  X.  Forty-one  of  these  bitmaps  are  also  available  in  the  Release  3 standard  distribu- 
tion. Table  G-l  lists  those  bitmaps  that  have  been  added  to  the  standard  distribution  in 
Release  4. 

Table  G-1.  Standard  Bitmaps  Available  as  of  Release  4 


calculator 

dropbar7 

dropbar8 

escherknot 

hlines2 

hlines3 

keyboard  16 

letters 

mailempty 

mailemptymsk 

mailfull 

mailfullmsk 

menu  10 

menu  12 

menul6 

menu8 

noletters 

plaid 

terminal 

xlogoll 

vlines2 

vlines3 

Standard  Bitmaps 
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Txl 

■ 

"23^ 

m 

black 

■ 

boxes 

calculator 

IS3HSb 

5cD°S 

cntr  ptr 

* 

cntr  ptrmsk 

♦ 

cross_weave 

dimplel 

dimple3 

do  t 

• 

dropbar 7 

O 

dropbar 8 

Q 

f lagdown 

-f 

lL, 

tlagup 

A 

mum 

f lipped_gray 

gray 

grayl 

gray  3 

hlines2 

hlines3 

icon 

□ 

keyboardl6 

O 

left  ptr 

* 

let t_ptrmsk 

letters 

1 ight_gray 

mai lempty 

M |B| 

mail 

B 

emptymsk 

mailtull 

LA* 

Bar  * 

mailfullmsk 

a 

menulO 

□ 

menul2 

UJ 

menul6 

a 

menu  8 

(D 

no le  t ter  s 

opendo  t 

O 

opendo tMask 

• 

right  ptr 

i 

right_ptrmsk 

root  weave 

scales 

sipb 

STTB 

sttb 

star 

* 

s tarMask 

* 

stipple 

target 

❖ 

term 

B 

inal 

tie  fighter 

fe* 

viines2 

vlines3 

weird  size 

i?  — 

wide  weave 

& “ 

wingdogs 

u 

xtd  icon 

aibicidieIfI 

xlogoll 

X 

xlogol6 

X 

xiogo32 

X 

xiogo64 

X 

Figure  G- 1.  The  Standard  Bitmaps 
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Figure  G-1.  The  Standard  Bitmaps  (continued) 
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Translation  Table  Syntax 


This  appendix  describes  the  basic  syntax  of  translation  table  resources, 
described  in  Chapter  9,  Setting  Resources. 

In  This  Chapter: 
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This  appendix  explains  some  of  the  more  complex  aspects  of  translation  table  syntax.  It 
probably  gives  more  detail  than  the  average  user  will  need,  but  we’ve  included  it  to  help  clar- 
ify this  rather  complicated  topic. 


Event  Types  and  Modifiers 

The  syntax  of  the  translation  table  is  sufficiently  general  to  encompass  a wide  variety  of 
events  and  circumstances.  Event  translations  can  be  specified  to  handle  characteristic  user 
interface  idioms  like  double  clicking,  dragging,  or  combining  keyboard  modifiers  with 
pointer  button  input.  To  specify  translations  that  use  these  features,  it  is  necessary  to  learn 
more  about  the  detailed  syntax  used  to  specify  translations. 

An  activity  susceptible  to  translation  is  a sequence  of  events  and  modifiers  (that  perform  an 
action).  Events  are  specified  in  angle  brackets  and  modifiers  precede  the  event  they  modify. 
The  legal  events  that  can  be  specified  in  a translation  are  as  shown  in  Table  H-l. 

Table  H-1.  Event  Types  and  Their  Abbreviations 


Event  Name 

Event  Type 

Abbreviations/Synonyms 

KeyPress 

Keyboard 

Key, KeyDown 

KeyUp 

Keyboard 

KeyRelease 

ButtonPress 

Mouse  Button 

BtnDown 

But tonRe lease 

Mouse  Button 

BtnUp 

BtnlDown 

Mouse  Button  Press 

Btn5Down 

BtnlUp 

Mouse  Button  Release 

Btn5Up 

Translation  Table  Syntax 
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Table  H-1.  Event  Types  and  Their  Abbreviations  (continued) 


MotionNotify 

ButtonMotion 
ButtonlMot ion 


Button5Mot ion 
EnterNotif y 
LeaveNotify 
Focusln 
FocusOut 
KeymapNotif y 
ColormapNot if y 
Expose 

Graph icsExpose 
NoExpose 

VisibilityNot if y 
CreateNotif y 
Dest royNotify 
UnmapNotify 
MapNot if y 
MapRequest 
Reparent Not if y 
Conf igureNot if y 
Conf igureRequest 
GravityNotif y 
ResizeRequest 
CirculateNot if y 
CirculateRequest 
PropertyNotif y 
SelectionClear 
Select ionReque st 
Select ionNot if y 


Motion  w/any  Button  Down 
Motion  w/Button  Down 

Mouse  in  Window 

Keyboard  Input  Focus 

Changed  Key  Map 
Changed  Color  Map 
Related  Exposure  Events 

Window  Management 


Intra-client  Selection 


Motion,  MouseMoved, 
Pt rMoved 
BtnMotion 
BtnlMotion 


Btn5Motion 
Enter, EnterWindow 
LeaveWindow,  Leave 


Keymap 

Clrmap 

GrExp 

NoExp 

Visible 

Create 

Destroy 

Unmap 

Map 

MapReq 

Reparent 

Configure 

Conf igureReq 

Grav 

ResReq 

Circ 

CircReq 

Prop 

SelClr 

SelReq 

Select 


Event  Name 


Event  Type 


Abbreviations/Synonyms 


Mouse  Motion 


The  possible  modifiers  of  an  event  are  listed  in  the  table.  The  modifiers  Modi  through  Mod5 
are  highly  system -dependent,  and  may  not  be  implemented  by  all  servers. 
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Table  H-2.  Key  Modifiers 


Event  Modifiers 

Abbreviation 

Ctrl 

c 

Meta 

m 

Shift 

s 

Lock 

1 

Any 

ANY 

None 

Modi 

1 

Mod5 

5 

Detail  Field 

To  provide  finer  control  over  the  translation  process,  the  event  part  of  the  translation  can 
include  an  additional  “detail.”  For  example,  if  you  want  the  event  to  require  an  additional 
keystroke,  for  instance,  an  A key,  or  a Ctrl-T,  then  that  keystroke  can  be  specified  as  a trans- 
lation detail.  The  default  detail  field  is  ANY. 

The  valid  translation  details  are  event-dependent.  For  example,  to  specify  the  above  example 
for  keypress  events,  you  would  use: 

<Key>A 

and: 


Ctrl<Key>T 

respectively. 

Key  fields  can  be  specified  by  the  keysym  value,  as  well  as  by  the  keysym  symbolic  name. 
For  example,  the  keysym  value  of  the  Delete  key  is  Oxffff.  Keysym  values  can  be  deter- 
mined by  examining  the  file  <Xll/keysymdef.h>  or  by  using  the  xmodmap  client.  (See  Chap- 
ter 1 1,  Setup  Clients , for  information  about  xmodmap.)  Unfortunately,  with  some  translations 
the  keysym  value  may  actually  be  required,  since  not  all  keysym  symbolic  names  may  be 
properly  interpreted. 
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Modifiers  can  be  closely  controlled  to  define  exactly  which  events  can  be  specified.  For 
example,  if  you  want  the  action  to  be  performed  by  pointer  button  clicks,  but  not  by  pointer 
button  clicks  with  the  Control  or  Shift  key  down,  these  limitations  can  be  specified.  Simi- 
larly, if  you  don’t  care  if  there  are  modifiers  present,  this  can  also  be  specified. 

Table  H-3  lists  the  available  event  modifiers. 

Table  H-3.  Event  Modifiers  and  their  Meanings 


Modifier 

Meaning 

None  <event> 

No  modifiers  allowed. 

<event> 

Doesn’t  care.  Any  modifiers  ok. 

Modi  Mod 

Modi  and  Mod2,  plus  any  others 
(i.e.,  anything  that  includes  ml  and  m2). 

IModl  Mod2<even/> 

Modi  and  Mod2  but  nothing  else. 

Modi  ~Mod2 <event> 

Modi  and  not  Mod2. 

Complex  Translation  Examples 

The  following  translation  specifies  that  function  / is  to  be  invoked  when  both  the  Shift  key 
and  the  third  pointer  button  are  pressed. 

Shif t<Btn3Down> : /() 

To  specify  that  both  the  Control  and  Shift  keys  are  to  be  pressed  use: 

Ctrl  Shif t<Btn3Down> : /() 

To  specify  an  optional  repeat  count  for  an  activity,  put  a number  in  parentheses  after  the 
action.  The  number  refers  to  the  whole  translation.  To  make  the  last  example  require  a 
double-click,  with  both  Control  and  Shift  keys  pressed,  use: 

Ctrl  Shift<Btn3Down>  (2)  : /( ) 

The  server  distinguishes  between  single-clicks  and  double-clicks  based  on  a pre-programmed 
timing  interval.  If  a second  click  occurs  before  the  interval  expires,  then  the  event  is  inter- 
preted as  a double-click;  otherwise  the  event  is  interpreted  as  two  single-clicks.  The  variable 
clickTime  is  maintained  deep  in  the  internals  of  X.  Unfortunately,  thus  far  there  is  no 
way  to  set  this  time  interval  to  match  user  preference.  Currently  it  is  set  to  be  200  mil- 
liseconds. 

A translation  involving  two  or  more  clicks  can  be  specified  as  (2+)  in  the  previous  example. 
In  general,  a plus  sign  following  the  number  n would  mean  n or  more  occurrences  of  the 
event. 
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Multiple  events  can  be  specified  by  separating  them  with  commas  on  the  translation  line.  To 
indicate  pressing  button  1,  pressing  button  2,  then  releasing  button  1,  and  finally  releasing 
button  2,  use: 

<BtnlDown>, <Btn2Down>, <BtnlUp>, <Btn2Up> : f ( ) 

Another  way  to  describe  this  action  in  English  would  be  to  say  “while  button  1 is  down,  click 
button  2.”  “Meaningless”  pointer  movement  is  generally  ignored.  In  the  previous  case,  for 
example,  if  pointer  motion  occurred  while  the  buttons  were  down,  it  would  not  interfere  with 
detection  of  the  event.  Thus,  inadvertent  pointer  jiggling  will  not  thwart  even  the  most  com- 
plex user-input  sequences. 
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X uses  many  common  terms  in  unique  ways.  A good  example  is  “ children . ” 
While  most,  if  not  all,  of  these  terms  are  defined  where  they  are  first  used  in 
this  book,  you  will  undoubtedly  find  it  easier  to  refresh  your  memory  by  look- 
ing for  them  here. 
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access  control  list 

active  window 

ASCII 

background 

background  color 
background  window 
binding 

bitmap 


X maintains  lists  of  hosts  that  are  allowed  access  to  each  server  con- 
trolling a display.  By  default,  only  the  local  host  may  use  the  dis- 
play, plus  any  hosts  specified  in  the  access  control  list  for  that  dis- 
play. The  list  is  found  in  /etc/Xn. hosts  where  n is  the  number  of  the 
display.  The  access  control  list  is  also  known  as  the  host  access  list. 

The  window  where  the  input  is  directed.  With  a “pointer  focus” 
window  manager  such  as  twm,  you  must  put  the  pointer  in  a window 
to  make  it  the  active  window.  The  active  window  is  sometimes 
called  the  focus  window. 

American  Standard  Code  for  Information  Interchange.  This  stan- 
dard for  data  transmission  assigns  individual  7-bit  codes  to  represent 
each  of  a specific  set  of  128  numerals,  letters,  and  control  charac- 
ters. 

Windows  may  have  a background,  consisting  of  either  a solid  color 
or  a tile  pattern.  If  a window  has  a background,  it  will  be  repainted 
automatically  by  the  server  whenever  there  is  an  Expose  event  on 
the  window.  If  a window  does  not  have  a background,  it  will  be 
transparent  See  also  foreground. 

The  color  that  determines  the  backdrop  of  a window,  for  example, 
on  monochrome  displays,  the  root  window  background  color  is  gray. 

A shaded  area  (also  called  the  root  window)  that  covers  the  entire 
screen  and  upon  which  other  windows  are  displayed. 

An  association  between  a function  and  a key  and/or  pointer  button. 
twm  allows  you  to  bind  its  functions  to  any  key(s)  on  the  keyboard, 
or  to  a combination  of  keys  and  pointer  button  (e.g.,  the  Control  key 
and  the  middle  button  on  a 3-button  pointer). 

A grid  of  pixels  or  picture  elements,  each  of  which  is  white,  black, 
or,  in  the  case  of  color  displays,  a color.  The  bitmap  client  allows 
you  to  edit  bitmaps,  which  you  can  use  as  pointers,  icons,  and  back- 
ground window  patterns. 
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border 


client 

colorcell 


colormap 


console  xterm  window 

default 


depth 

device-dependent 

display 


A window  can  have  a border  that  is  zero  or  more  pixels  wide.  If  a 
window  has  a border,  the  border  can  have  a solid  color  or  a tile  pat- 
tern, and  it  will  be  repainted  automatically  by  the  server  whenever 
its  color  or  pattern  is  changed  or  an  Expose  event  occurs  on  the 
window. 

An  X application  program.  There  are  client  programs  to  perform  a 
variety  of  tasks,  including  terminal  emulation  and  window  manage- 
ment. Clients  need  not  run  on  the  same  system  as  the  display  server 
program. 

An  entry  in  a colormap  is  known  as  a colorcell.  An  entry  contains 
three  values  specifying  red,  green,  and  blue  intensities.  These  val- 
ues are  always  16-bit  unsigned  numbers,  with  zero  being  minimum 
intensity.  The  values  are  truncated  or  scaled  by  the  server  to  match 
the  display  hardware.  See  also  colormap. 

A colormap  consists  of  a set  of  colorcells.  A pixel  value  indexes 
into  the  colormap  to  produce  intensities  of  red,  green,  and  blue  to  be 
displayed.  Depending  on  hardware  limitations,  one  or  more  color- 
maps  may  be  installed  at  one  time,  such  that  windows  associated 
with  those  maps  display  with  true  colors.  Regardless  of  the  number 
of  installable  colormaps,  any  number  of  virtual  colormaps  can  be 
created.  When  needed,  a virtual  colormap  can  be  installed  and  the 
existing  installed  colormap  may  have  to  be  uninstalled.  The  color- 
map  on  most  systems  is  a limited  resource  that  should  be  conserved 
by  allocating  read-only  colorcells  whenever  possible,  and  selecting 
RGB  values  from  the  predefined  color  database.  Read-only  cells 
may  be  shared  between  clients.  See  also  RGB. 


This  xterm  window  is  the  first  window  to  appear  on  your  display. 
Exiting  the  console  window  kills  the  X server  program  and  any 
associated  applications.  Also  called  the  login  xterm  window. 

A function-dependent  value  assigned  when  you  do  not  specify  a 
value.  For  example,  specifying  the  -rv  option  with  xterm  reverses 
the  foreground  and  background  colors  for  the  xterm  window.  If  you 
do  not  specify  this  option,  the  default  foreground  and  background 
colors  are  used. 

The  depth  of  a window  or  pixmap  is  the  number  of  bits  per  pixel. 

Aspects  of  a system  that  vary  depending  on  the  hardware.  For 
example,  the  number  of  colors  available  on  the  screen  (or  whether 
color  is  available  at  all)  is  a device-dependent  feature  of  X. 

A set  of  one  or  more  screens  driven  by  a single  X server.  The  DIS- 
PLAY environment  variable  tells  programs  which  servers  to  connect 
to,  unless  it  is  overridden  by  the  -display  command  line  option. 
The  default  is  always  screen  0 of  (display)  server  0 on  the  local 
node. 
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event 

exposure 


focus  window 


font 


font  directory 


foreground 
foreground  color 
geometry 

hexadecimal 


Something  that  must  happen  before  an  action  can  occur. 

Window  exposure  occurs  when  a window  is  first  mapped,  or  when 
another  window  that  obscures  it  is  unmapped,  resized,  or  moved. 
Servers  do  not  guarantee  to  preserve  the  contents  of  windows  when 
windows  are  obscured  or  reconfigured.  Expose  events  are  sent  to 
clients  to  inform  them  when  contents  of  regions  of  windows  have 
been  lost  and  need  to  be  regenerated. 

The  window  to  which  keyboard  input  is  directed.  By  default,  the 
keyboard  focus  belongs  to  the  root,  which  has  the  effect  of  sending 
input  to  whichever  window  has  the  pointer  in  it  (if  you  are  using  a 
“pointer  focus”  window  manager,  such  as  twm).  However,  some  cli- 
ents may  automatically  take  the  focus,  which  means  they  may  send 
input  to  a particular  window  regardless  of  the  position  of  the 
pointer. 

A style  of  text  characters.  Fonts  and  X font  naming  conventions  are 
described  in  Chapter  5,  Font  Specification.  Samples  of  Release  3 
and  4 screen  fonts  are  pictured  in  Appendix  E. 

By  default.  Release  3 and  Release  4 fonts  are  stored  in  three  sub- 
directories of  lusrlliblXll /fonts:  called  mi  sc,  75  dpi,  and  100dpi. 
(Release  2 fonts  are  stored  in  the  directory  lusrlliblXll  /fonts)  You 
can  specify  an  alternative  font  search  path  for  the  server  with  the 
xset  client. 

The  pixel  value  that  will  actually  be  used  for  drawing  pictures  or 
text  is  referred  to  as  the  foreground. 

The  color  in  which  the  text  in  windows  and  menus,  or  graphics  out- 
put are  displayed. 

The  specification  for  the  size  and  placement  of  a window,  which  can 
be  specified  with  the  -geometry  option.  This  option  takes  an 
argument  of  the  form:  widthxheight+xoff±yoff. 

A base- 16  arithmetic  system,  which  uses  the  digits  A through  F to 
represent  the  base- 10  numbers  10  through  15.  Hexadecimal  nota- 
tion (called  hex  for  short)  is  frequently  used  with  computers  because 
a single  hex  digit  can  represent  four  binary  digits  (bits).  The  table 
below  shows  the  equivalence  between  hex  digits  and  binary  num- 
bers. 


Hex 

Binary 

Hex 

Binary 

Hex 

Binary 

Hex 

Binary 

0 

0000 

4 

0100 

8 

1000 

C 

1100 

1 

0001 

5 

0101 

9 

1001 

D 

1101 

2 

0010 

6 

0110 

A 

1010 

E 

1110 

3 

0011 

7 

0111 

B 

1011 

F 

1111 
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highlighter 

X clients  accept  a special  hexadecimal  notation  (prefixed  by  a # 
character)  in  all  command  line  options  relating  to  color.  See  Chap- 
ter 8,  Command  Line  Options,  for  more  information. 

The  horizontal  band  of  color  that  moves  with  the  pointer  within  a 

menu. 

hot  spot 

The  reference  point  of  a pointer  that  corresponds  to  its  specified 
position  on  the  display.  In  the  case  of  an  arrow,  an  appropriate  hot 
spot  is  its  tip.  In  the  case  of  a cross,  an  appropriate  hot  spot  might 
be  its  center. 

icon 

A small  symbol  that  represents  a window  but  uses  little  space  on  the 
display.  Converting  windows  to  icons  allows  you  to  keep  your  dis- 
play uncluttered. 

input  device 

Hardware  device  that  allows  you  to  input  information  to  the  system. 
For  a window-based  system,  a keyboard  and  pointer  are  the  most 
common  input  devices. 

keyboard  focus 

See  focus  window. 

menu 

A list  of  commands  or  functions,  listed  in  a small  window,  which 
can  be  selected  with  the  pointer. 

modifier  keys 

Keys  on  the  keyboard  such  as  Control,  Alt,  and  Shift.  X programs 
recognize  a set  of  “logical”  modifier  key  functions  that  can  be 
mapped  to  physical  keys.  The  most  frequently  used  of  these  logical 
keys  is  called  the  “meta”  key. 

mouse 

An  input  device  that,  when  moved  across  a flat  surface,  moves  the 
pointer  symbol  correspondingly  across  the  display.  The  mouse 
usually  has  buttons  that  can  be  pressed  to  send  signals  that  in  turn 
accomplish  certain  functions.  The  mouse  is  one  type  of  pointer 
device;  the  representation  of  the  mouse  on  the  screen  is  also  called 
the  pointer.  (See  pointer.) 

occluding 

In  a windowing  system,  windows  may  be  stacked  on  top  of  each 
other  much  like  a deck  of  cards.  The  window  that  overlays  another 
window  is  said  to  occlude  that  window.  A window  need  not  com- 
pletely conceal  another  window  to  be  occluding  it 

padding 

Space  inserted  to  maintain  alignment  within  the  borders  of  windows 
and  menus. 

parameter 

A value  required  before  a client  can  perform  a function.  Also  called 
an  argument. 

pixel 

The  smallest  element  of  a display  surface  that  can  be  addressed. 

pointer 

A generic  name  for  an  input  device  that,  when  moved  across  a flat 
surface,  moves  the  pointer  symbol  correspondingly  across  the  dis- 
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property 

play.  A pointer  usually  has  buttons  that  can  be  pressed  to  send  sig- 
nals that  in  turn  accomplish  certain  functions.  A mouse  is  one  type 
of  pointer  device. 

The  pointer  also  refers  to  the  symbol  on  your  display  that  tracks 
pointer  movement  on  your  desk.  Pointers  allow  you  to  make  selec- 
tions in  menus,  size  and  position  windows  and  icons,  and  select  the 
window  where  you  want  to  focus  input.  A pointer  can  be  repre- 
sented by  a variety  of  symbols.  (See  text  cursor.)  Some  typical  X 
pointer  symbols  are  the  I-beam  and  the  skull  and  crossbones. 

Windows  have  associated  properties,  each  consisting  of  a name,  a 
type,  a data  format,  and  some  data.  The  X protocol  places  no  inter- 
pretation on  properties;  they  are  intended  as  a general-purpose  data 
storage  and  intercommunication  mechanism  for  clients.  There  is, 
however,  a list  of  predefined  properties  and  property  types  so  that 
clients  can  share  information  such  as  resize  hints,  program  names, 
and  icon  formats  with  a window  manager.  In  order  to  avoid  passing 
arbitrary  length  property-name  strings,  each  property  name  is  asso- 
ciated with  a corresponding  integer  value  known  as  an  atom. 

reverse  video 

Reversing  the  default  foreground  and  background  colors. 

RGB 

An  additive  method  for  defining  color  in  which  tenths  of  percent- 
ages of  the  primaries  red,  green,  and  blue  are  combined  to  form 
other  colors. 

root  window 

A shaded  area  (also  called  the  background  window)  that  covers  the 
entire  screen  and  upon  which  other  windows  are  displayed. 

screen 

A server  may  provide  several  independent  screens,  which  may  or 
may  not  have  physically  independent  monitors.  For  instance,  it  is 
sometimes  possible  to  treat  a color  monitor  as  if  it  were  two  screens, 
one  color  and  one  black  and  white. 

scrollbar 

A bar  on  the  side  of  an  xterm  window  that  allows  you  to  use  the 
pointer  to  scroll  up  and  down  through  the  text  saved  in  the  window. 

The  number  of  lines  saved  is  usually  greater  than  the  number  of 
lines  displayed  and  can  be  controlled  by  the  saveLines  resource 
variable. 

select 

A process  in  which  you  move  the  pointer  to  the  desired  menu  item 
or  window  and  click  or  hold  down  a pointer  button  in  order  to  per- 
form some  action. 

selection 

Selections  are  a means  of  communication  between  clients  using  pro- 
perties and  events.  From  the  user’s  perspective,  a selection  is  an 
item  of  data  that  can  be  highlighted  in  one  instance  of  an  application 
and  pasted  into  another  instance  of  the  same  or  a different  applica- 
tion. The  client  that  highlights  the  data  is  the  owner,  and  the  client 
into  which  the  data  is  pasted  is  the  requestor.  Properties  are  used  to 
store  the  selection  data  and  the  type  of  the  data,  while  events  are 
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server 


text  cursor 


tile 


window 


window  manager 


used  to  synchronize  the  transaction  and  to  allow  the  requestor  to 
indicate  the  type  of  data  it  prefers  and  to  allow  the  owner  to  convert 
the  data  to  the  indicated  type  if  possible. 

The  combination  of  graphics  display,  hardware,  and  X server  soft- 
ware that  provides  display  services  for  clients.  The  server  also 
handles  keyboard  and  pointer  input. 

The  standard  underscore  or  block  cursor  that  appears  on  the  com- 
mand line  or  in  a text  editor  running  an  xterm  window.  To  make  the 
distinction  clearer,  the  cursor  that  tracks  the  movement  of  a mouse 
or  other  pointing  device  is  referred  to  as  the  pointer.  The  pointer 
may  be  associated  with  any  number  of  cursor  shapes,  and  may 
change  shape  as  it  moves  from  window  to  window. 

A pattern  that  is  replicated  (as  if  laying  a tile)  to  form  the  back- 
ground of  a window  or  other  area.  This  term  is  also  used  to  refer  to 
a style  of  window  manager  or  application  that  places  windows  side 
by  side  instead  of  allowing  them  to  overlap. 

A region  on  your  display  created  by  a client.  For  example,  the 
xterm  terminal  emulator,  the  xcalc  calculator,  and  the  bitmap  graph- 
ics editor  all  create  windows.  You  can  manipulate  windows  on  your 
display  using  a window  manager. 

A client  that  allows  you  to  move,  resize,  circulate,  and  iconify  win- 
dows on  your  display. 
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Index 


A 

acceleration 
cursor  14 
pointer  222 
access  control 
/etc/Xn. hosts  file  547 
user-based  548 
xdm  548 
XDMCP  548 
xhost  547 

action  field  (twm  window  man- 
ager) 208 
active  window  592 
aliasing  font  names  93  - 95 
arrays 

converting  to  bitmaps  109,  119 
atobm  (array  to  bitmap  converter) 
109-120 

authentication  widget  535,  538, 
544 

auto-repeat  option  (xset)  109,  221 
average  width  (fonts)  87 


B 

background 
colors  225 

-background  option  (-bg)  169 
background  window  see  also  root 
window  6 
-bd  option  1 69 

BDF  (Bitmap  Display  Format)  for 
fonts  549 

bdftosnf  (font  compiler)  549 
bell  volume  (xset)  203,  219 


-bg  option  1 69 
binding 

button/key  (.twmrc  file)  206 
keys  45 

tight  vs.  loose  (resources)  184 
bitmap  (creating  graphics)  14,  109 
- 118 

command  boxes  112 
description  of  109 
invoking  109,112 
window  110 

Bitmap  Display  Format  (BDF)  for 
fonts  549 

-bitmap  option  (xsetroot)  224,  225 
bitmaps 

converting  to  arrays  109,  119 
creating  from  cursor  119 
editing  111 
standard  693 

bmtoa  (bitmap  to  array  converter) 
109-120 

Boolean  variables  205 
border  color  option  (-bd)  1 69 
border  width  option  168 
Bourne  shell  script  528 
bug  compatibility  mode  220 
button 

bindings  206 
codes  237 

command  151,188,596 
logical  228 
-bw  option  168 
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c 

C shell  script  528 
calculator  (xcalc)  14  see  also 
xcalc 

description  132 
function  of  keys  133 
terminating  133 
character  set  88 
character-cell  fonts  82 
class 

definition  184 
resource  names  184 
click-to-type  focus 
see  explicit  focus  592 
client 

command  line  options  1 64 
customizing  15,45,181 
definition  12 
desk  accessories  129 
display  manager  14 
display  options  1 64 
location  of  default  values  1 82 
placing  45 
removing  141 
standalone  14 
user-contributed  150 
window  manager  13 
clipboard  72,191  see  also  x clip- 
board 

CLIPBOARD  selection  65, 

191  - 192  see  also 
xclipboard 

clock  130  see  also  oclock 
Close  (Window  Menu)  606 
color 

changing  color  name  database 
550 

determining  number  available 
174 

displaying  174 
for  screen  elements  169 
hexadecimal  specification  172 
menus  212 

problems  allocating  551 
RGB  model  173 
specifying  root  window 
(xsetroot)  225 
colorcell 
definition  174 
read-only  175 
read/write  175,  223 
shared  175 
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colormap  146,  223 
description  174 
command  boxes  (bitmap) 
112-118 
command  buttons 
Maximize  596 
Minimize  596 
command  button  widget  151 
command  line  options  (client) 

163  - 177,  181 
-fit  (font)  104 
-background  169 
-bd  (border  color)  169 
-bg  (background)  169 
-border  color  169 
-borderwidth  168 
-bw  (border  width)  1 68 
-display  164 
-fn  (font)  176 
-foreground  169 
-geometry  166 
-iconic  176 
list  of  standard  163 
-name  194 
-reverse  177 
-tide  165 

-xrm  (set  resources)  194 
commands 
bitmap  editing  111 
executing  system  211 
for  terminating  xterm  window 
54 

Main  Options  menu  53 
menu  212 
pointer  112 
Tek  Options  menu  59 
text  editing  widget  156 
VT  Options  menu  56 
console  messages  550 
context  field  (twm  window  man- 
ager) 207 

Control  key  156,189,207 
conventions  of  book  v 
copying  selections  in  xterm  win- 
dows 61,  152 
and  xcutsel  66 

create  font  databases  92  see  also 
mkfontdir 
cursor  font  633 
customizing 
clients  15,  181 
keyboard  227 
mwm  610  - 629 
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pointer  227 
twm  46, 203 
xdm  536  - 544 
cut  buffer  strings  61 
vs.  selections  65 


D 

database  resource  196 
DEC  VT102  14 
-def  option  (xsetroot)  224 
defaults 

setting  application  182,  187 
deiconifying  windows  36,  597 
Delete  key  157 
Delete  (Twm  menu)  43 
deleting  windows  43 
desk  accessories  14,  129  - 139 
dialog  box  widget  151 
directories 
font  90 
display 
depth  of  174 
server  11 
setting  219 

DISPLAY  environment  variable 
165,528 

display  fonts  80,  97  - 98  see  also 
xfd 

display  manager  14  see  also  xdm 
-display  option  1 64 
display  window  information  144 
see  also  xwininfo 
dump  file  see  window  dump  file 

E 

-edit  option  (xrdb)  197 
enlarging  windows  597,  606 
environment  variables 
DISPLAY  148,  165,  528,  609 
TERMCAP  74,  526 
X ENVIRONMENT  199 
error  log  file  (xdm)  539 
/etc/ttys  (starting  X from)  545 
event  translations  188,189,538 
syntax  697 
events 

definition  188 
input  188 


Exit  (Twm  menu)  44 
exiting 

window  manager  44 
xmag  123 
xman  pro  gram  138 
xterm  window  25 
explicit  focus  592 


F 

feedback  boxes  623 
-fg  option  169 
files 

.twmrc  35,  45,  46 
.Xdefaults  52 
.Xresources  45,51,52 
log  550 
resource  181 
.twmrc  15,203 
.uwmrc  557 
.xinitrc  182,527 
Xreset  536,  542,  544 
.Xresources  182 
Xresources  536,  542,  544 
.xsession  182,535 
Xsession  538 

xfd  (font  displayer)  97  - 105 
xset  (set  display  preferences) 
219-223 

xterm  (terminal  emulator)  menus 
Main  Options  50,  52 
xwd  (window  dump)  140  - 141 
Focus  (Twm  menu)  43 
focus  policies  (mwm) 
explicit  592 
focus  window  43 
focusing 
definition  8 

font  displayer  see  also  xfd  15 
font  path  option  (xset)  221 
fonts  see  also  Release  2 fonts  and 
Release  3 fonts 
75 -dpi  vs  100-dpi  85  - 87 
aliases  for  93 
average  width  87 
bdftosnf  (font  compiler)  549 
Bitmap  Display  Format  (BDF) 
549 

bold  and  demi-bold  84 
character  set  88 
character-cell  82,  87 
conventions  of  in  book  v 
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create  font  databases  (mkfontdir) 
92 

directories  90 
display  (xfd)  79,  80 
displaying  (xfd)  79  - 80, 97  - 98 
families  8 1 , 90 
fonts  .dir  file  91 
foundries  87 
italic  vs.  oblique  84 
list  available  (xlsfonts)  80 
making  server  aware  of  aliases 
95,  549 

mkfontdir  (create  font  databases) 
92,  549 

monospace  87 
naming  conventions  80 
number  of  fonts  available  81 
on  command  line  176 
pictures  of  Release  3 and  4 639 
point  size  84 
previewing  (xfontsel)  98 
printer  79 
proportional  82,  87 
reverse  italic  and  reverse  oblique 
84 

screen  79,  176 
search  path  90,  9 1 
selecting  (xfontsel)  80,  98 
serif  and  sans  serif  84,  88 
Server  Natural  Format  (SNF) 

549 

set  width  87 

showsnf  (display  compiled 

font)  549 

slant  84 

style  88 

weight  84 

wildcarding  88,  89,  90 
fonts. alias  file  93 
fonts  .dir  file  91,93,549 
foreground  colors  225 
-foreground  option  (-fg)  1 69 
foundries  (fonts)  87 
-frame  option  140 
function  names  field  (twm  window 
manager)  208 


G 

generating  display  information 
149  see  also  xdpyinfo 
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-geometry  option  166-167 
-grammar  option  (xmodmap)  234 
graphics 

creating  with  bitmap  109-118 
magnifying  with  xmag  122 
graphics  utilities  109-125 
-gray  option  (xsetroot)  224 
grip 

definition  153 


H 

-help  option  (xsetroot)  224 
hexadecimal  color  specification 
172 


I 

icon 

definition  7 

displaying  window  as  36 
moving  39 

starting  window  as  176 
turning  a window  into  207 
icon  box  626  - 629 
-iconic  option  176 
Iconify  (Twm  menu)  36 
iconifying  windows  25,  36,  596, 
605 

icons 

manipulating  607  - 608 
input  events  188 
instance 
definition  184 
resource  names  184 
ISO  Latin-1  character  set  88 


K 

key  binding  45,  206 
keyboard 
bell  219 

customization  227 
preferences  219 
shortcuts  36,  45,  557 
keyclick  volume  220 
keycode 
definition  229 
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keys 

binding  207 
Control  156,189,207 
Delete  157 
mapping  230,  235 
Meta  26, 156, 189,207,231 
modifier  26,  227,  227  - 237 
Shift  207 

keys  field  (twm  window  manager) 
207 

keystrokes 
missing  46 
keysym 
definition  229 
determining  232 
mapping  234 
values  699 

keyword  variables  206 
Kill  (Twm  menu)  43 
killing 

client  window  141 
oclock  143 
server  141 
windows  43 

with  Window  Menu  button  602 
xterm  window  25,  54 


L 

led  option  (xset)  221 
list  fonts  80  see  also  xlsfonts 
list  variables  206 
list  window  tree  146  see  also 
xlswins 
log  files  550 
logging  in  14,  20 
logical 

font  convention  80 
keyname  26,  230 
pointer  button  228 
loose  bindings  184,186 
Lower 

Twm  menu  42 
Window  Menu  606 
lowering  windows  42 

M 

magnifying  screen  122  see  also 
xmag 


Main  Options  menu  50 
commands  53 
mode  toggles  52 
manipulating  icons  607  - 608 
using  Window  Menu  607 
mapping 
definition  188 
event-action  190 
Meta  key  207 

modifier  keys  227,  230,  236 
possibilities  with  xmodmap  234 
translation  table  189 
Maximize 

command  button  597  - 598 
Window  Menu  item  606 
menus 
color  212 
creating  new  203 
defining  in  .twmrc  file  209,  210 
executing  system  commands 
from  211 
Preferences  209 
Root  Menu  (mwm)  608  - 610 
Tek  Options  49,  58 
Tektronix  49 
Twm  35,  203 
twm  (window  manager)  50 
VT  Fonts  57 
VT  Options  55,  59 
Window  Menu  (mwm) 

602  - 608 
WindowOps  556 
xterm  (terminal  emulator)  50 
-merge  option  (xrdb)  196 
Meta  key  26,  156,  189  - 190,231 
definition  207 
mapping  207 
Minimize 

command  button  596  - 597 
Window  Menu  item  605 
mkfontdir  (create  font  databases) 
92,  549 

-mod  option  (xsetroot)  225 
mode  toggles 
Main  Options  menu  52 
Tek  Options  menu  58 
VT  Options  menu  56 
Modes  menu  see  VT  Options 
menu 

modifier  keys  26,  227 
mapping  227  - 237 
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monospaced  fonts  82 
Motif  (window  manager)  see 
mwm 

mouse  option  (xset)  222 
Move 

Twmmenu  39 
Window  Menu  604 
moving 
windows  594 
on-screen  objects  39,  45 
mwm  (window  manager) 

591  -629 

activating  changes  to  610 
client-specific  resources  624 
component  appearance  resources 
623 

customizing  610-629 
manipulating  windows  594 
overview  591 
restarting  610 
selecting  windows  592 
setting  resources  622  - 623 
specific  resources  624 
starting  592 
.mwmrc  file 

customizing  mwm  through  610 

N 

-name  option  194 
naming  conventions 
fonts  80 

New  Window  command 
Root  Menu  609 

New  Window  (WindowOps  menu) 
558 

numeric  variables  206 


O 

occluded 
definition  40 
oclock  (analog  clock)  27, 

130-  131,206,213 
killing  131,  143 

options  see  command  line  options 
OSF/Motif  (window  manager) 

591  - 629  see  also  mwm 
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P 

pasting  selections  in  xterm  win- 
dows 64,  152 
and  xcutsel  66 
path 

including  X in  526 
pipes  and  pointer  interaction  141 
point  size  84 
pointer 

acceleration  222 

bindings  206 

buttons  237 

commands  112 

context  of  207 

customization  227 

defining  button  functions  206 

definition  7 

mapping  236 

possible  cursor  images  633 
pointer  button  see  button 
pointer  button  field  (twm  window 
manager)  206 

postscript  translation  15  see  also 
xpr 

Preferences  menu 
example  of  209 
PRIMARY  selection  61,152 
printer  fonts  see  fonts 
printing  utilities  140  - 141 
proportional  fonts  82 


Q 

Quit  command  (Main  Options 
menu)  54 


R 

Raise  (Twm  Menu)  41 
raising  windows  41,42,598 
read-only  colorcell  175,223 
read/write  colorcell  175,  223 
redrawing  windows  55 
Refresh  command 
Root  Menu  610 
refreshing  the  screen  550 
Release  2 fonts 
directory  104 

vs.  subsequent  releases  104 
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Release  3 fonts 
aliasing  93 

create  font  databases  (mkfontdir) 
92,  549 
directories  90 
fonts  .dir  file  91,549 
making  server  aware  of  aliases 
95, 549 

pictures  of  639 
Release  4 fonts 
directories  90 
pictures  of  639 
removing  windows  43 
resize  74 

Resize  (Twm  menu)  38 
resizing  windows  38,  74 
problems  due  to  38 
using  pointer  599 
resource  database  manager  15, 
192, 181  see  also  xrdb 
RESOURCE.MANAGER 
property  195 
resources 

class  names  of  184,  185 
client-specific  624 
component  appearance  623 
event  translations  of  188-192 
files  of  181 

instance  names  of  184,  185 
list  of  common  1 87 
management  of  181,  195  - 199 
precedence  rules  for  185 
removing  definitions  197 
sample  file  193 
setting  181  - 199,  195 
setting  with  mwm  622 
specific  appearance  624 
specification  of  181,  183,  185 
syntax  of  182,  183 
tight  vs.  loose  bindings  186 
translation  table  of  188 
Restart 

Root  Menu  610 
Twm  menu  44 
restarting  mwm  610 
Restore  (Window  Menu)  607 
-reverse  option  177 
reverse  video  177,  225 
RGB 

color  model  173-174 
values  225 


Root  Menu 

New  Window  command  609 
Refresh  command  610 
Restart  command  610 
Shuffle  Down  command  609 
Shuffle  Up  command  609 
root  window  224 
definition  6 
setting  (xsetroot)  224 
-rv  option  177 


S 

screen 

magnifying  122 
resolution  85,  86,  87 
saver  option  (xset)  222 
screen  fonts  see  fonts 
scripts 

Bourne  shell  528 
C shell  528 
startup  527  - 530,  538 
scrollbar 

creating  in  xterm  window  59 
VT  Options  menu  59 
widget  152 
search  path 
including  X in  526 
setting  22 
security  issues 
/etc/Xn.hosts  file  547 
user-based  access  548 
xdm  548 
XDMCP  548 
xhost  547 
selections 
copying  61,  152 
manipulating  65 
pasting  64,  152 
saving  multiple  68,  72 
text  62 

vs.  cut  buffers  65 
Send  CONT  signal  command 
(Main  Options  menu)  54 
Send  HUP  Signal  command  (Main 
Options  menu)  54 
Send  INT  Signal  command  (Main 
Options  menu)  53 
Send  KILL  Signal  command 
(Main  Options  menu)  54 
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Send  STOP  signal  command 
(Main  Options  menu)  54 
Send  TERM  Signal  command 
(Main  Options  menu)  54 
server 

closing  connection  141 
control  access  (xdm)  548 
control  access  (xhost)  547 
definition  11 
display  11 
starting  19,  527 

Server  Natural  Format  (SNF)  for 
fonts  549 

set  width  (fonts)  87 
shell  environment  variables  ee 
environment  variables 
shell  scripts 
Bourne  528 
C 528 
startup  527 
Shift  key  207 

showsnf  (display  compiled  font) 
549 

Shuffle  Down  (Root  Menu)  609 
Shuffle  Up  (Root  Menu)  609 
Size  (Window  Menu)  605 
SNF  see  Server  Natural  Format 
549 

-solid  option  (xsetroot)  225 
spacing  (fonts)  87 
stacked  windows 
changing  order  of  40,  42 
starting  X 19-30 
bringing  up  window  manager  23 
BSD  4.3  545 
from /etc/ttys  545 
placing  clients  45 
setting  search  path  526 
setting  terminal  type  526 
steps  for  22 
System  V 545 
xdm  (display  manager) 

531  -544 

xinit  (start  X server)  22,  545 
startup  scripts  528,  538 
submenu  210 

system  management  525  - 55 1 
system  .mwmrc  file  612-619 
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T 

Tek  Options  menu  50 
commands  59 
description  of  items  58 
mode  toggles  58 
Tektronix  4014  14 
temporary  xterm  windows 
running  commands  in  75 
TERMCAP 

environment  variable  526 
entry  for  xterm  74 
terminal  emulator  49  see  also 
xterm 

definition  14 
terminal  type 
setting  526 
xterm  73 

terminating  xterm  window  25,  54, 
176 

text 

copying  and  pasting  61,  64,  66, 
72 

string  variables  205 
switching  buffer  and  selection 
(xcutsel)  66 

text  editing  widget  154,  156 
thumb  (scrollbar) 
definition  152 
tight  bindings  184,  186 
title  area  of  window  594 
-title  option  1 65 
titlebar  595 
description  7 

in  twm  window  manager  23, 
34-35 

in  xterm  window  20 
titlebutton  bindings  206 
Toolkit  options  see  command  line 
options 
toolkits 
definition  182 
translation  table 
definition  188 
example  of  190 
mappings  in  189 
syntax  190,697-701 
Twm  menu  35  - 45 
Delete  43 
Exit  44 
Focus  43 
Iconify  36 
Kill  43 
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Lower  42 
Move  39 
Raise  41 
redesigning  203 
Resize  38 
Restart  44 

twm  (window  manager)  13,22 
action  field  208 
and  stacking  windows  40 
background  processes  23 
bringing  up  23,  535 
context  field  207 
customizing  46,  203 
defining  keys  207 
example  of  modified  213 
exiting  44 

function  names  field  208 
keys  field  207 
menus  50 
overview  33 
placing  clients  45 
pointer  button  field  206 
restarting  44 
setting  variables  205 
titlebars  34  - 35 
Twm  menu  35 
.twmrc  file  35 
.twmrc  file  15,35,45  -46, 
203-216 

button/key  bindings  206 
changing  defaults  205 
example  of  203 
menus  defined  by  209  - 210 
modifying  213 
setting  variables  205 

U 

UNIX  commands 
running  in  temporary  xterm  75 
user-contributed  clients  150 
Utilities  menu 
example  of  209 
uwm  (window  manager)  13 
overview  555 
.uwmrc  file  557 
WindowOps  menu  556 
.uwmrc  file  557 


V 

variables  165  see  also  environ- 
ment variables 
Boolean  205 
keyword  206 
list  206 
numeric  206 
resource  167 
setting  .twmrc  205 
vertical  panes  153 
viewport  widget  154 
Vpaned  widget  153 
VT  Fonts  menu  50 
description  of  items  57 
VT  Options  menu  50 
Allow  80/132  Column  Switching 
56 

description  of  items  55 
mode  toggles  56 
VT102  (DEC)  14 
Modes  menu  55 
VT  Options  menu  55 


W 

widget 

attributes  184 

authentication  535,  538,  544 
binding  (loose  vs.  tight)  184 
command  button  151 
defining  conventions  184 
definition  150 
dialog  box  151 
hierarchy  183 
scrollbar  152 
text  editing  154,156 
viewport  154 
Vpaned  153 

wildcarding  font  names  88-90 
window  dump  14  see  also  x wd 
window  dump  file 
creating  (xwd)  140 
displaying  (xwud)  140 
printing  140 
to  printer  (xdpr)  141 
undumping  (xwud)  141 
window  manager  13,  33  - 46,  203 
see  also  twm,  uwm,  mwm 
steps  for  starting  23 
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Window  Menu 
Close  606 
displaying  602 
Lower  606 

manipulating  icons  with  607 
Maximize  606 
Minimize  605 
Move  604 

reasons  for  using  602 
removing  menu  604 
Restore  607 
selecting  items  603 
Size  605 

Window  Menu  command  button 
602 

WindowOps  menu 
New  Window  558 

windows 

creating  22,  23,  558 
definition  6 
deiconifying  36,  597 
displayed  as  icons  36 
displaying  information  about 
144 

enlarging  597 
exiting  xterm  25 
focus  43 
geometry  of  166 
hierarchy  of  146 
icon  box  626 
iconifying  25,  36,  596 
killing  (Twm  menu)  43 
killing  (Window  Menu  button) 
602 

killing  (xkill)  141 
lowering  42 
manipulating  33,  555 
manipulating  (mwm)  594 
maximizing  596 
minimizing  596 
moving  39,  594 
raising  41,42,598 
redrawing  55 
resizing  38,  74,  558,  599 
root  6,  224 
selecting  (mwm)  592 
stacked  40,  42 
starting  as  icon  176 
switching  focus  between  25 
Tektronix  49 
terminating  54 
title  165 
title  area  594 
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vertically  tiled  153 
width  of  168 


X 

X Window  System 
description  of  5 
display  server  1 1 
overview  of  architecture  10 
xbiff  (mail  notification)  133, 212 
xcalc  (calculator)  14,  132  - 133, 
212, 528,598 

xclipboard  (save  text  selections) 
65,68,  191 
Release  3 72 

xclock  (analog  or  digital  clock) 

14,  130-131,206 
killing  130 

xcutsel  (exchange  cut  buffer  and 
selection)  65,  66 
.Xdefaults  file  52 
vs.  xrdb  192 

.Xdefaults  file  see  .Xresources 
xdm  (display  manager)  14 
access  control  features  548 
authentication  widget  535,  538, 
544 

configuration  file  532 
customizing  536  - 544 
error  log  file  539 
login  window  20 
standard  session  535 
starting  X with  531  - 544 
stopping  xdm  and  the  server  540 
Xreset  539 

Xresources  file  538,  544 
.xsession  file  538 
Xsession  file  538 
Xstartup  539 

xdpr  (window  dump  to  printer) 

141 

xdpyinfo  (list  display  information) 
149 

xedit  (text  editor)  71,  154,207 
XENVTRONMENT  environment 
variable  199 
xev  (track  events)  232 
xfd  (font  displayer)  15,  80,  95, 

141 

xfontsel  (select  font)  80 
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xhost  (control  access  to  server) 
547 

xinit  (start  X server)  22,  527,  545 
.xinitrc  file  527 

xkill  (remove  window)  141  - 144 
xload  (poll  system  load  average) 
28,  134 

xlsclients  (list  running  clients) 

148  - 149 

xlsfonts  (list  available  fonts)  80 
x Is  wins  (list  window  tree) 
146-148 

xmag  (magnify  screen  portion) 
122-125 

description  of  122 
quitting  123 
xman 

as  a viewport  154 
xman  (display  manual  pages)  135 
Release  3 138 
xmodmap  (modifier  key  and 
pointer  customization) 

227  - 237 

change  map  233  - 237 
display  key  map  230 
display  pointer  map  236 
grammar  option  234 
xpr  (postscript  translation)  15, 
140-141 

xrdb  (resource  database  manager) 
15, 192-  199, 527 
-edit  option  197 
loading  new  values  to  196 
querying  196 
removing  definitions  197 
saving  definitions  197 
setting  resources  with  195 
syntax  195 
using  195 

xrefresh  (refresh  screen)  55,610 
Xreset  file  536,542,544 
.Xresources  file  15,  51,  52,  182, 
536,  538,  542,  544 
sample  193 
.xresources  file 

customizing  mwm  through  610 
-xrm  option  194 
.xsession  file  535,  538 
Xsession  file  538 
xset  (set  display  preferences)  14, 
91,210 

auto  display  option  221 
auto-repeat  option  109 


font  path  option  221 
mouse  option  222 
xsetroot  (set  root  window  charac- 
teristics) 224  - 237 
-bitmap  option  224 
-def  option  224 
xterm  menus  49  - 59  see  also 
Main  Options  menu,  Tek 
Options  menu,  Vt  Options 
menu 
Modes  50 
Tek  Options  49  - 50 
Tektronix  49-50 
VT  Fonts  50 
VT  Options  50 
xterm  50 

xterm  (terminal  emulator) 
and  termcap  526 
control  sequences  68 1 
creating  window(s)  22,  558 
default  size  45 
multiple  xterms  23 
overview  14,  49 
pasting  and  copying  selections 
152 

running  command  in  temporary 
window  75 
scrollbar  59 
Tektronix  window  49 
TERMCAP  74 
terminal  type  73 
terminating  25,  54 
xwd  (window  dump)  14 
xwininfo  (display  window  infor- 
mation) 144  - 146 
xwud  (window  undumper)  140, 
141 
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